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About This Book 



NetView Customization: Using Assembler describes the ways system programmers 
can tailor or supplement the NetView™ program, to satisfy unique requirements or 
operating procedures. 

This book discusses the uses and advantages of user-written programs (exit rou- 
tines, command processors, and subtasks). It provides instructions that guide the 
programmer through the mechanics of designing, writing, and installing these pro- 
grams. 

This book contains product-sensitive programming interfaces provided by NetView. 
Installation exits and other product-sensitive interfaces are provided to allow the 
customer installation to perform tasks such as product tailoring, monitoring, mod- 
ification, or diagnosis. They are dependent on the detailed design or implementa- 
tion of the product. Such interfaces should be used only for these specialized 
purposes. Because of their dependencies on detailed design and implementation, 
it is to be expected that programs written to such interfaces may need to be 
changed in order to run with new product releases or versions, or as a result of 
service. 



Who Should Use This Book 



This book is intended for experienced system programmers who are knowledge- 
able in assembler language. These users are presumed to be familiar with the 
functions NetView provides automatically. 

Secondary users include operators, network planners, designers, and systems 
analysts. Secondary users may also include ibm marketing representatives and 
instructors. 



What Is New for NetView Release 3 



Although the assembler-language programming interface described in this book is 
not new for NetView Release 3, this book documents the interface in a more 
useable manner. In addition, the following list of changes and additions have been 
made in assembler-language support provided by NetView Release 3: 

• Templates are provided in the NetView sample library for a user exit routine, a 
command processor, and an optional subtask. See "Template for a User Exit 
Routine" on page 48, "Template for a Command Processor" on page 71, and 
"Template for an Optional Task" on page 95. 

• Several sample command processors and user exit routines are provided in 
the NetView sample library. See Appendix A on page 225. 

• In order to avoid possible conflicts with user-written exit routines, null exit rou- 
tines for dsiexo2A and dsiexi6 are no longer provided. 
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• Information is provided in Chapter 6 on writing rexx user functions, and the 
dsirxebs macro is provided to support this process. See Chapter 6 on 
page 109 and the dsirxebs macro on page 213. 

• The dsirxcom macro is provided to support access to variables in a calling rexx 
command list. See "DSIRXCOM - Access REXX Variables" on page 207. 

• A priority option has been added to the dsimqs macro. See "DSIMQS - 
Message Queuing Services" on page 185. 

• The sub option has been added to the dsiprs macro to request the parse 
service routine to accept quoted substrings. See "DSIPRS - Parsing 
Services" on page 193. 

• A compcde option has been added to the dsipop macro. See "DSIPOP - 
Remove Long Running Command" on page 190. 

• The roll option has been changed and the promote option has been added to 
the dsipush macro. See "DSIPUSH — Establish Long Running Command" on 
page 202. 

• The dsiwls macro can now be used to write to a sequential log. See"DSIWLS 
- Write Log Services" on page 214. 

• Focal point alert forwarding is now provided. The cross-domain alerts can be 
accessed in an xitci exit routine running under the bnjdserv dst. See "XITCI: 
CNM Interface Input" on page 44. 



Terms Used in This Book 



Command list A list of commands and statements designed to perform a spe- 
cific function for the user. Command lists can be written in rexx 
or in NetView Command List Language. 

Command procedure Either a command processor written in a high-level language 
(hll) or a command list. See command list and command 
processor for further explanation. 

Command processor A user-written module designed to perform a specific func- 
tion. Command processors, which can be written in assembler 
or a high-level language (hll), are invoked as commands. 

High-level language (hll) A programming language that does not reflect the struc- 
ture of any particular computer or operating system. For 
NetView Release 3, the high-level languages supported are pl/i 
and c. 

NetView Command List Language An interpretive language unique to NetView that 
is used to write command lists. 

REXX Restructured Extended Executor. An interpretive language used 

to write command lists. 

User exit routine A user-written routine that receives control at predefined user 
exit points. User exit routines can be written in assembler or a 
high-level language (hll). 
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Where To Find More Information 



The following list shows all of the publications in the NetView Release 3 library, 
arranged according to related tasks. For more information on these and other 
related publications, see "Bibliography" on page 269. 
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Network Program Products General Information GC30-3350 
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Chapter 1. Assembler Application Program Interface (API) 

Before reading this chapter, you should have read the section on designing user- 
written functions and the NetView™ customization facilities in the NetView 
Customization Guide. 

To use this manual most effectively, you should have in mind a specific command 
processor or user exit that you want to write in assembler. For example you might 
want to write a command processor to run under a Data Services Task (dst) to 
store some data in a vsam file or a command processor to run on an Operator 
Station Task (ost) to display information on an operator's screen. The NetView 
Customization Guide contains information to help you decide which command 
processors and user exits you need to write in order to build your application and 
what the appropriate language is for each of those pieces of code. 

Why Write in Assembler Language? 

Although more effort is required to code in assembler language, this language, by 
its very nature, has greater flexibility than other languages supported by NetView: 

• Regression support: Your assembler language command processors from 
earlier releases of NetView, with or without modification, will be supported. 

• Display Flexibility: Although full screen display support is provided to all lan- 
guages via the VIEW command, you may wish to take advantage of special fea- 
tures of your terminal hardware, such as wide screens or cursor dependent 
function. By writing in assembler language you gain direct access to the 3270 
data stream commands. 

• Special Data Handling: Assembler language affords you the ability to do 
special handling, such as reentrant updates to a global data structure, or 
complex functions at operator logoff or ABEND-reinstatement. 

• Privileged Functions: In assembler language, you have unrestricted access to 
all system functions and macros. 

• Interaction with other commands: In assembler language, you have the ability 
to wait on, or examine the status of, asynchronous events other than the 
standard set that the view command uses. This would include completion of 
commands under another task or timed events. 

• Performance: While high-level language routines supported by NetView run 
faster than interpreted command lists, some kinds of data manipulation can be 
done even faster at the assembler-language level. 

Additionally, you will want to understand the requirements and environments of 
command processors at the assembler level if you write assembler language sub- 
routines for your high-level language command processors. 
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Overview of the Chapters 

The following describes the chapters in this manual. 

• Chapter 2. Designing Your Assembler Module - This chapter discusses the 
information needed to design your assembler module. 

• Chapter 3. Writing User Exit Routines - This chapter discusses how to design, 
code and install user exit routines that take advantage of the NetView program 
exits at strategic processing points. 

• Chapter 4. Writing Command Processors in Assembler Language - This 
chapter discusses how to design, code and install assembler-language 
command processors for NetView. 

• Chapter 5. Writing User Subtasks - This chapter discusses the two methods for 
writing user subtasks. 

• Chapter 6. Writing REXX User Functions - This chapter explains how to add 
additional functions or expand or replace rexx functions that already exist in 
the NetView/REXX environment. 

• Chapter 7. Control Block Reference - This chapter describes control block 
fields related to customization interfaces. 

• Chapter 8. Macro Reference - This chapter describes the purpose and coding 
of the NetView program macros. 



Preparing Your Code for Use 



Before putting your code into production, develop test scenarios for the major func- 
tions. Use the NetView trace facility when testing so that you can later analyze 
any errors or abends your code generates. The format of the trace command is 
found in NetView Operation. Running trace is particularly helpful for verifying 
input to user exit routines, to dsipss, and to dsimqs. 

When testing new command processors, use res=n in the cmdmdl definition so that 
the object code can be replaced without recycling NetView. 

If you have included automated operation support in your user-written code, you 
may test the results of automation using any of the following methods: 

• Log on to NetView using an automated operator task user id and password 
(your autotask will be treated as an operator task when directly logged on) and 
observe the output on the screen. 

• Examine the network log, the mvs system log, and the hard copy task output for 
messages associated with the autotask's user id. 

To avoid possible conflict between your code and NetView services currently in 
use, consider running the code on a separate NetView or test machine, or during a 
time of day when NetView is not used heavily. To test your code, you must restart 
NetView, except for pre-defined non-resident command processors. (If there is 
little risk of conflict, you may simply add your code to the NetView production 
library currently in use.) 

Once the test system is up, perform the test scenarios and verify that the results 
and output of your code are correct. If they are correct, put the code into pro- 
duction and begin using it normally. 
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Chapter 2. Designing Your Assembler Module 



This chapter presents information on NetView services available for user-coded 
command processors, user exits, and user subtasks. Refer to Chapter 8 on 
page 161 for detailed information on the NetView service macros that are dis- 
cussed. See Appendix A on page 225 for assembler coding samples incorporating 
these macros. 



Task Structure 

The NetView task environment consists of a main task and six types of subtasks. 

MNT The main task initializes NetView. It provides an environment for the sub- 
tasks and oversees their creation and cleanup. The main task also pro- 
vides limited exit routines that modify processing under the main task. 

OST An operator station task lets an operator enter commands and receive 
network messages. An ost is created for an operator at logon. 

The unattended operator task is a special type of ost that is started by the 
autotask command. This task functions as an ost with no associated lu. 
Independent of vtam or terminals, this task performs all line-mode com- 
mands (no full-screen commands) and allows multiple command proce- 
dures to run concurrently in separate subtasks. The unattended operator 
task is a basis for automation. 

The mvs console operator task is another special type of ost that is started 
by the autotask command with the console operand. Independent of vtam, 
this task performs all line-mode commands (no full-screen commands) and 
allows multiple mvs console operators to access NetView, each under their 
own mvs console operator task. 

NNT A NetView-NetView task allows an operator to access another NetView 

(usually in another domain), send commands to that NetView, and receive 
messages from that NetView. The start domain command causes an nnt to 
be created in the other domain. 

HCT A hard-copy task logs the activity of one or more osts using 328x printers. 
The start hcl command creates an hct. 

PPT The primary programmed operator interface (poi) task receives unsolicited 
messages from vtam and receives message traffic exchanged between the 
system console and vtam. Additionally, the ppt provides timer services 
and runs commands and command lists. There is one ppt per NetView. 
The ppt is created when NetView starts. 

DST Data services tasks provide command, message, and exit functions. In 
addition, data services tasks can manage vsam orcNM facilities. You can 
create new subtasks to perform any or all of these functions. The dst is 
created when NetView starts or when start task is issued. 

OPT Optional tasks provide increased flexibility beyond the subtasks NetView 
provides. For example, an opt could be used to provide unique command 
interfaces or more precise control of work dispatching than standard 
command processors running under a DST-based task could provide. You 
can define the opt to start when NetView starts or when start task is 
issued. 
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General Coding Guidelines 
Processing Environment 

User written code of all types is given control in problem program state and with a 
user memory protection key 1 . NetView and all user written code given control 
under NetView is authorized. This gives the user the option of invoking privileged 
system services or entering supervisor state or changing the key. However, 
control should be returned to NetView in the same program state and key as when 
user code was entered. 

Except as noted in Chapter 7, all NetView control blocks are accessible in the user 
key. Unless specifically noted in Chapter 8, all NetView services must be invoked 
in problem program state and the user key. 

The setting of the tvbinxit bit in the task vector block (tvb) when NetView calls 
user-written code determines the environment under which your code will be proc- 
essed. When a NetView task is initially dispatched, the tvbinxit bit is off. Thus, if 
the task calls user-written code at this time, the code processes under the mainline 
environment. 

Whenever the operating system interrupts mainline processing, NetView sets the 
tvbinxit bit on. Thus, any user-written code called at this time is processed under 
the TVBiNxiT=on environment. 

Not all tasks can run all types of user-written code. In fact, each task has unique 
restrictions that limit the code it can process. Table 1 indicates the types of code 
that can run under each task in the mainline environment. The figure also indi- 
cates which types of code can run when the tvbinxit bit in the task vector block 
(tvb) is set on. (Since you define which commands and functions will run under an 
oPTSubtask, that subtask is not included in Table 1.) 

Table 1. Processing Environment of User-Written Programming 





Main 
Task 


OST 


NNT 


HCT 


PPT 


DST 


TVBINXIT 
Set On 


User exit routines 


V 


V 


V 


V 


V 


V 


V 


Regular command processors 




V 


V 




V 






Immediate command processors 




V 


V 








V 



Data services command processors V 



Coding Requirements 

This section discusses the general restrictions that you must observe when writing 
your code. The control blocks and macros mentioned in this section are described 
in more detail in Chapter 7 and in Chapter 8. 
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Restrictions when TVBINXIT is On: See Table 2 on page 32 to determine which 
user exits must interrogate the tvbinxit bit. No user exit should change the value of 
TVBINXIT. When your code receives control with tvbinxit set on, the following 
restrictions apply: 

• Messages may be sent only to the immediate message area of the operator's 
screen. To send these messages, you must specify macro dsipss with the 
type=immed option. You may also use dsimqs to queue messages to be proc- 
essed after the asynchronous exit completes. 

• Do not code your program to cause a system wait state. A system wait may 
produce an interlock. For example, if an irb exit were to wait for a resource 
being used by the mainline routine, the resource would not be released since 
the irb exit is interrupting the mainline routine. 

To avoid causing a system wait state, keep in mind the following: 

- Do not issue macro dsiwat. 

- Do not issue macro dsidks or any other disk services macros. Disk i/o can 
cause a wait state. 

• Only immediate commands may be called directly, dsimqs can be used to 
invoke regular commands. For more information, see "Invoking Commands" 
on page 21. 

Variable Names: Do not use the following as a prefix for any variable or message 
you name in your code: 

• Any NetView component prefix, aau, bni, bnj, bnk, cnm, dsi, or dwo. 

• Any NetView control block suffix, such as swb or pdb. 

Macro Usage: When a NetView macro and an operating system macro perform 
equivalent services, use the NetView macro. This ensures that the source code for 
your program will be transportable across NetView operating systems. However, if 
you must use an operating system macro, be careful that its function does not con- 
flict with a function NetView may be performing. For example, if the operating 
system macro stimer were issued under the ppt, NetView timer services would be 
disrupted. 

Register Usage: Follow these guidelines when using registers for user exit rou- 
tines, command processors, and subtasks: 

• Save registers at entry to the user code and restore them before returning 
control to NetView. Set register 15 with your return code. 

• Avoid using registers 0, 1, 14, and 15; they are reserved for NetView macro 
expansion. 

• Register 13 should contain the address of a standard 72-byte save area. 

• Return control to the location in NetView specified by register 14. 

• Do not rely on the contents of registers and 2 through 12 for constant values 
on entry to user code. Their contents vary. 

Reentrancy: Make sure your code is reentrant, to allow the one copy of the 
program to be used concurrently by more than one task. For example, a command 
processor may be invoked from two or more tasks simultaneously and thus 
execute simultaneously under multiple tasks. 
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Reentrancy is not required for certain user exits or for optional tasks. SeeTable 2 
on page 32 for more information. 

MVS/XA Considerations: NetView supports any valid combination of addressing 
mode (amode) and residency mode (rmode). Depending on the mode your code is 
currently running in, NetView provides the appropriate services. In addition, it pro- 
vides macro parameters where necessary to enable you to specify 24-bit or 31 -bit 
addressing for your special requirements. Also, NetView provides appropriate res- 
idency for the control blocks your code accesses, such as use, cwb, and bufhdr. 
For example, if your command processor is loaded with amode =24, then the cwb 
passed to it will reside below 16 Mb. 

To conserve storage below 16 Mb, 31-bit addressing is recommended except when 
restricted by your use of mvs/xa interfaces to the contrary. 



Control Blocks 



To perform the essential functions of presenting information to end users and 
invoking commands, your code must include the necessary control block mappings 
and establish addressability to other control blocks. For details on the purpose 
and contents of the control blocks mentioned below, refer to Chapter 7 on 
page 119. 

Control Blocks Overview 

• mvt - Main Vector Table (dsect dsimvt) 

One mvt for NetView, contains NetView global information. 

• tvb - Task Vector Block (dsect dsitvb) 

One tvb per task, contains task definition and status information. 

• tib - Task Information Block (dsect dsitib) 

One tib per active task, contains additional information pertaining to a task. 

• swb - Service Work Block (dsect dsiswb) 

Work area/parameter list for NetView macro services. An swb is provided at 
entry to a command processor or user exit. 

• cwb - Command Work Block (dsect dsicwb) 

One per command, contains savearea, work area, and pointers to other 
NetView control blocks. 

• pdb - Parse Descriptor Block (dsect dsipdb) 

In a command processor environment, the pdb contains parse information for 
the command. In a user exit environment, the pdb contains parse information 
for the user message buffer. 

• bufhdr - NetView Buffer Header (dsect bufhdr included with dsect dsitib) 

Maps the control information which precedes commands and messages in 
NetView buffers. 

• ifr - Internal Function Request (dsect dsiifr) 
A multi-purpose NetView buffer: 

— Command ifr (contains a command) 
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- Automation ifr (contains automation information and message(s)) 

• use - User Exit Parameter List (dsect dsiuse) 
Contains user exit information. 

• dsrb - Data Services Request Block (dsect dsidsrb) 

cwb extension used by Data Service Command Processors in the dst (Data 
Service Task) environment only. 

Including Control Blocks: At assembly, include dsects for the NetView control 
blocks that have fields your code uses. You must include the following control 
blocks in your code: 

• For user exit routines, include the user exit parameter list (use). Since the use 
contains the addresses of the tvb, swb, pdb, and bufhdr (defined with the tib), 
you need to include these control blocks, as well. 

Note: Each tvb will address its associated tib and the mvt. 

• For command processors, include the command work block (cwb). Since the 
cwb contains the addresses of its swb, pdb, and bufhdr (defined with the tib), 
you also need to include these control blocks. In addition, data services 
command processors (dscps) require the data services request block (dsrb). 

• For user subtasks, include the task vector block (tvb). Then include any other 
control blocks necessary for your user-defined task. 

Depending on the particular service facilities your code uses, you will need to 
include various other control blocks. 

Figure 1 on page 12 illustrates the interconnections between the control blocks. 
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User Exit Routines 
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Figure 1. Overview of the Control Blocks for User-Written Programming. For each type of 
user-written code, the tvb provides access to the mvt and, thus, to the svl, as 
shown in the subtasks diagram. The field displacements suggested in the figure 
are not representative of the actual field displacements. 
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Use macro dsicbs to include dsects for the appropriate control blocks. For 
example, you might code the dsicbs macro in a command processor as follows: 



DSICBS DSICWB,DSISWB,DSIMVT,DSIPDB,DSITVB,PRINT=NO 



This instruction includes the cwb, swb, mvt, pdb, and tvb. This instruction also 
specifies, with print=no, that control block expansions are not to be printed. 

Establishing Addressability: You must establish addressability to a control block 
before referencing its fields. The following example shows how you could estab- 
lish addressability to the mvt for a command processor: 



USING DSICWB.l 
L register, CWBTIB 

USING DSITIB, register 
L registerJIBTVB 

USING DSITVB, register 
L register, TVBMVT 

USING DSIMVT, register 



Work Block Services 

The service work block (swb) is needed when your code invokes NetView service 
facilities. The command work block (cwb) is used as command processor input. 
Macro dsilcs obtains and releases swbs or cwbs, as shown in the following 
example: 



DSILCS CBADDR=MYSWBPTR,SWB=GET 

LTR REG15,REG15 

BNZ ERRORSWB 

L REG2JVBTIB 

L REG3,MYSWBPTR 

ST REG2,SWBTIB-DSISWB(REG3) 

DSILCS CBADDR=MYSWBPTR,SWB=FREE 



In this example, an swb is to be obtained and its address is to be placed in 
myswbptr. The second and third statements test for a good return code in register 
15. If the macro was successful, you must initialize the swbtib field to yourTiB 
address before the swb may be used. After use, the swb should be released using 

DSILCS. 



Basic Module Services 



Chapter 2. Designing Your Assembler Module 13 



Standard NetView Buffer Structure 

All message and command buffers must include an initialized buffer header 
(bufhdr) structure preceding the message data or command text, bufhdr is a sepa- 
rate dsect contained in the dsitib (Task Information Block) control block (use dsicbs 
to include dsitib when your module references bufhdr fields). The following 
section presents an overview of the bufhdr fields. See Chapter 7 on page 119 for 
additional details. 





Standard Buffer Header 




0(0) 


HDRMLENG 
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HDRBLENG * 

Total Length of Buffer 
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Message Type 
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BUFHDR Extension (HDRMCEXT) (used by DSIMQS Macro) 
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28 (1C) 



HDRNEXTM 
Chain Field 



HDRSENDR 

Operator ID of Sending Subtask 



Figure 2. Buffer Header (BUFHDR) 
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Field Description 

hdrbleng Contains the actual length of the entire buffer: header, plus text, plus 
unused space. If the buffer is to be released with dsifre, this length is 
used. The length may be up to 32,767 bytes. 

hdrmleng Indicates the length in bytes of the text data in the buffer. 

hdrind Should be set to zero except when using title-line output. See "Title- 

Line Output" later in the chapter for details. 

hdrmtype Contains a character that indicates the current usage of the buffer. It 
may also indicate the origin of the command. If the buffer is written 
out using the dsipss macro, this field is displayed and logged. 

hdrtdisp The offset from the start of the buffer header to the first byte of text. 

hdrtstmp Contains the time that the command was received, in the packed 

decimal from X'hhmmssOC where hh is the hours of the day from 00 
to 23, mm is the minutes of the hours from 00 to 59, ss is the seconds 
of the minute from 00 to 59, and 0C is a packed decimal sign. See the 
dsidatim macro instruction. 

hdrdomid Shows the identifier of the domain where the message originated. 
This field is displayed and logged. 

HDRMCEXT (BUFHDR extension) 

An extension to the bufhdr that is used when a buffer is transferred 
from one subtask to another. It is built by the dsimqs macro when cre- 
ating a buffer for the destination task. Other buffers do not need 
these fields. 

hdrnextm An internal NetView field that is used to chain buffers together. 

hdrsendr Contains the originator's operator id, which is the contents of the 
sender's tvbopid field. 

text Can start anywhere after the reserved area in a standard buffer or 

after hdrsendr in a buffer with a message command extension. Use 
hdrtdisp to locate the start of text. 

Note: Relationship of hdrbleng, hdrmleng, and hdrtdisp: Since hdrtdisp points to 
the start of the buffer data and hdrmleng is the length of the buffer data, then at no 
time should hdrtdisp + hdrmleng be greater than hdrbleng. This implies that the 
value of hdrmleng can range in value from to (hdrbleng -hdrtdisp). 



Dynamic Storage Services 



Storage services enable you to get and free storage for your code. Use macro 
dsiget to get storage and macro dsifre to free storage, as shown in the following 
example: 



DSIGET IV=4096,A=ST0RPTR,TASKA=(MYTVBREG) ,Q=N0 
LTR REG15.REG15 
BNZ ERR0RGET 



DSIFRE LV=4096,A=ST0RPTRJASKA=(MYTVBREG) ,Q=N0 



The above example requests that 4,096 bytes of storage be obtained. The address 
of the storage is to be placed in the fullword named storptr. The second and third 
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statements test for a good return code in register 15 before you use the storage. 
When the storage is obtained, it has been cleared to zeros. 

After use, you must free the storage using the same value for the q option as you 
used previously to get the storage. 

Note: The use of taska is recommended, since it can help you avoid addressing 
the wrong tvb control block. It must contain the address of the tvb for the subtask 
where the code is executing. Use the taska parameter for both non-queued (q = no) 
and queued (q=yes) storage. 

Queued Storage: You may also use the dsiget q=yes option to enable NetView to 
release queued storage at logoff or task termination, which facilitates error 
recovery. The following example illustrates this usage: 



DSIGET LV=4096,A=STORPTR,TASKA=(MYTVBREG) ,Q=YES,BNDRY=PAGE 
LTR REG15, REGIS 
BNZ ERRORGET 

DSIFRE A=STORPTR,TASKA=(MYTVBREG) ,Q=YES 



In this example, q=yes indicates that NetView is to keep track of the 4,096 bytes of 
storage in an internal queue. To support this internal queue, q=yes generally gets 
eight more bytes of storage than requested. However, if bndry = page is specified, 
eight extra bytes are not gotten and thus page alignment is not affected. 

Storage obtained with one call must be released with one call. 

NetView ignores the storage length indicated by dsifre when q=yes is specified, lv 
is optional when q=yes and is ignored. 



Message Processing 
Creating Messages 



The dsimds (Message Definition Service) macro provides the ability to create a load 
module of user defined message skeletons. Each defined message skeleton may 
contain up to nine variable length text inserts. 

The dsimbs (Message Building Service) macro will take message insert text and 
combine it with the specified message skeleton and return a completed message 
buffer which can be used for displaying the message. 

See Chapter 8 on page 161 for additional details on using the dsimds and dsimbs 
macros. 

See samples CNMS4271, cnms4278, and CNMS4281 for an example of creating user 
defined messages with dsimds and dsimbs. 
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Displaying Information to NetView Operators 

The primary channels for presenting information to the operator are the following: 

• The terminal screen using macro dsipss 

• The network log, mvs system log, sequential log, and hard-copy log using 

DSIWLS 

• The system console using dsiwcs. 

Figure 3 shows how these macros communicate with the operator. The logging 
and system console services are simply invocations of the dsiwls and dsiwcs 
macros. For detailed information on these services, see Chapter 8 on page 161. 
Message presentation via dsipss and dsimqs is more complex and is described on 
the following pages. 



Terminal for this 
Operator Station 



DSIPSS 

TYPE = OUTPUT 
IMMED 
ASYPANEL 



System 
Operator's <- 
Console 



DSIWCS 



Domain Boundary 




NetView Operator 
(Operator Station Task) 



DSIWLS 



Network Log or 
Hard-Copy Log 
for this Operator 
Station 



DSIPSS 
TYPE = XSEND 



DSIMQS 



Another Subtask 
in this Domain 



DSIPSS 

TYPE = OUTPUT 
IMMED 



NetView-NetView Task (NNT) 



Figure 3. Using Macros to Communicate from an OST 



Macro dsipss can present information in any of the following three screen modes; 
dsimqs is limited to standard mode and title-line mode. 



Standard Mode 



From an ost or nnt, messages are sent to the screen with a 
12-character prefix followed by data. The prefix includes a 
1-character code for the entry type (from hdrmtype) and a 
domain name field (from hdrdomid) indicating the domain that 
generated the message. If the message exceeds the screen 
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Title-Line Mode 



Full-Screen Mode 



width, it is split between two words. The message is con- 
tinued on the next screen line and indented 12 characters. 

A variation on standard mode output is the immediate 
message. It appears at the bottom of the screen as a single 
71-character message with neither prefix nor continuation 
lines. 

Thus, to present a message in standard mode, you may use 
any of these methods: 

• Issue DSIPSS TYPE = OUTPUT 

• ISSUe DSIPSS TYPE = IMMED 

• Issue dsimqs to queue a hdrtypeu message buffer to the 

OST. 

• ISSUe DSIPSS TYPE = FLASH 

See sample CNMS4274for an example of standard mode 
output. 

Title-line presentation services send sequences of messages 
to the operator, without allowing other messages to be inter- 
spersed. The messages appear on the screen in a tabular 
format, with one or more title lines. Title-line messages have 
no prefix and may use the full width of the screen. Messages 
longer than screen width are truncated. For more informa- 
tion on how to specify this type of output, see "Title-Line 
Output" on page 19. 

Title-line mode messages and system multiline write-to- 
operator (mlwto) messages are treated as a single message 
by dsiexo2a, dsiexi6, &wait in NetView command list language, 
trap and wait in rexx and high-level language command pro- 
cedures, the message automation table, and the assign 
command. When creating your title-line mode messages, 
make sure the first line does not conflict with any iBM-sup- 
plied message number. Some message number format 
similar to the IBM message number format is recommended to 
allow these facilities to be used with your messages. 

See sample cnms4273 for an example of title line output. 

Application-built 3270 data streams containing commands, 
orders, and data are sent to the screen. In this way, a full 
screen of information can be presented. Full-screen 
command processors, which run under an ost, are the only 
type of user-written code (except for user exit dsiex-12) that 
can utilize full-screen mode. For this reason, this topic is 
addressed more fully under "Writing a Full-Screen Command 
Processor" on page 61. 

See sample CNMS4279 for an example of full screen output. 
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Title-Line Output 



Title-line output is best suited to message groups that can be presented on a single 
screen, since you cannot scroll backward. Figure 4 shows an example of title-line 
output. 
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Figure 4. Example of Title-Line Output 

The first line NetView generates is a separator that consists of just the message 
type and the domain id. (In Figure 4, "=" is the message type and "netvi" is the 
domain id.) The separator is followed by the title, which can be one to six lines. 
The title is followed by the data lines. The screen wraps around until all the data is 
displayed. (If the data lines continue to the next screen, the title is redisplayed at 
the top of the new screen.) 

To use title-line output, format and send one message buffer for each line of infor- 
mation as follows: 

1. Set the hdrmtype field in the bufhdr to hdrtypel ( = ). 

2. As you build each message buffer, do the following: 

• For a line that is part of the title, set hdrind to hdrlnlbl. Your title can 
contain one to six lines. 

• For a data line, set hdrind to hdrlndat. 

• For the last line of data, set hdrind to hdrlnend. 

3. When the message buffer is ready for presentation, do one of the following: 

• From any NetView subtask, use dsimqs to queue the message buffer to the 
desired ost. This is the recommended method and is appropriate to use 
from the destination ost; however, the output will not begin to be displayed 
until you return control to the ost. 

• From an ost or nnt, not in an exit, issue dsipss type = output to send the 
message buffer. 
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In either case, the output will not begin to be displayed until after the data-end line 
has been sent. 

NetView groups all title-line buffers at the ost until a buffer marked as data end 
(hdrlnend) is received. Upon receipt of the end message, the title lines are sent to 
the screen. These lines appear directly under the previous message. Each data 
line appears one line at a time. If the message sequence fills one screen and 
begins another, the title lines are repositioned at the top of the screen, followed by 
the next data lines. This process continues until all the messages appear on the 
screen. 

Each buffer sent to the screen contains at least one character. To print a blank 
line, place a blank character (X'40') in the buffer. If a line of title-line output is 
longer than the width of the screen, the line will be truncated to screen width. 

Displaying Messages to the System Console 

The dsiwcs (Write to Console Service) macro will display a message buffer at the 
system console. The message buffer must have an initialized NetView buffer 
header (bufhdr) and the text will be truncated to 120 characters when displayed on 
the console. 



Logging Messages 



The dsiwls (Write to Log Service) macro can be used to record information on the 
network log, the mvs system log, a hard copy log, an external log, or a sequential 
log. 

Network Log, System Log, and Hard Copy Task: dsiwls will log data to the network 
log, system log, and the hard-copy task. The defaults and override commands will 
determine the general logging environment (the current logging actions will be 
applied to the message buffer passed to the dsiwls macro). If the message is 
passed in an aifr buffer, the aifr settings will be checked to determine which of the 
logs the message will actually be logged in. 

See sample CNMS4272 for an example of writing to the logs. 

External Logging: dsiwls also provides the ability to log data to the NetView- 
defined external logging task (task id is dsieltsk). The external logging task can be 
defined at installation time to record to the smf log (restricted to mvs) or to a user 
defined data set. If a user defined dataset is to be used, the xitxl exit must be 
coded to actually do the logging of the data. The external logging task is a 
NetView-implemented Data Services Task (dst). See Chapter 8 on page 161 for 
information on dst's and refer to the NetView Installation and Administration Guide 
for details on installing the external logging task. The xitxl exit is described in 
Chapter 3 on page 31. 

Sequential Logging: dsiwls also provides the ability to log data to a sequential 
logging task. The sequential logging task will record the data using the Basic 
Sequential Access Method (bsam). Multiple sequential logging tasks can be 
defined at installation time. Refer to the NetView Installation and Administration 
Guide for details on installing sequential logs. 

See sample CNMS4275 for an example of writing to a sequential log. 
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Invoking Commands 

Commands can either be called directly or they can be scheduled. Calling a 
command directly requires the following: 

1. The command environment must be initialized (required control blocks must 
be acquired, etc.). 

2. The dsices (Command Entry Service) macro must be invoked to look up the 
address of the command processor in the NetView command table and then a 
branch is performed to the command processor. 

To schedule a command, the dsimqs (Message Queuing Service) must be used. 
Scheduling a command under a task results in a command buffer being placed on 
one of the task's message queues (there may or may not be other command 
buffers ahead of the scheduled command's). When the scheduled command's 
buffer is processed off the message queue, the command processor will be 
invoked. 

Calling a Command Directly 

The following steps must be followed to call a command processor directly: 

All the following are required to invoke a command processor or command list: 

• A CWB 

• An swb 

• A command buffer 

• A PDB 

• A save area 

• Registers 1, 13, 14, and 15. 

Obtaining a Command Work Block (CWB): A command processor requires a 
command work block (cwb) for use as a parameter list, a save area, and a work 
area. A cwb may be preallocated (and reused) or may be obtained by issuing the 
dsilcs macro. Before calling the command processor, the tib address must be 
stored in the cwbtib field. 

Obtaining a Service Work Block (SWB): The routine that invokes a command 
processor must provide an swb. The swb may be preallocated, obtained with the 
dsilcs macro, or may be one the invoker was passed. This control block must also 
have its swbtib field pointing to the tib. The swb address must be stored in 
cwbswb. 

Building a Command Buffer: Each command is invoked with a command buffer 
containing a verb and optional operands. The command buffer is prefixed with the 
buffer header (bufhdr). Each bufhdr field must be initialized except the message 
command extension hdrmcext. The address of this command buffer is stored in 

CWBBUF. 

Obtaining a Parse Descriptor Block (PDB) and Parsing the Command: The routine 
must obtain storage for a pdb to parse the command for the command processor to 
be called. The size of the storage for the pdb may be obtained by issuing the 
dsiprs macro with the pdbsize option. The usual size is 160 bytes. After the 
storage is obtained (from preallocated storage or with dsiget), the address is 
stored in the cwbpdb field. The control block header (cbh) is built and cbhid is set 

Chapter 2. Designing Your Assembler Module 21 



to the value defined by symbol cbhpdb. cbhtype is zeroed, and the pdb length is 
stored in the cbhleng prior to invoking the dsiprs macro. Issuing dsiprs fills in the 
pdb including the pdbbufa pointer to the command buffer, the parse elements, and 
the number of parse elements. 

Looking Up the Command Processor Address: After the command is parsed, the 
command must be found in the NetView system command table (sct). The 
command may be looked up in one of three ways: 

• With the parsed command in the pdb 

• Without prior parsing 

• By command processor module name (the module name is known but the verb 
name may change, as in a synonym). 

The dsices macro returns the address of the command's system command table 
entry. This address is returned in an area passed on the dsices macro as the 
sctaddr parameter. This address points to an sct entry (mapped by the sce), and 
the address must be stored in the pdbcmda field. 

When the dsices macro returns to the caller, the return code indicates whether the 
command is immediate, regular, or both. If tvbinxit is on, then the pdbimmed bit 
must be set on if the dsices return code indicates that the command to be called 
was defined as type =i (immediate) or type =b (both). 

You may call regular commands only when tvbinxit is off and only from task types 
ost, nnt, and ppt. You may call immediate commands only when tvbinxit is on and 
only from task types ost and nnt. Unless otherwise noted in this book, do not call 
NetView-written type d commands. 

Calling the Command Processor: Register 1 must point to the cwb (which now in 
turn points to the pdb, swb, tib, and the command buffer). Register 13 must point to 
a save area (where it is probably already set, because a save area is required for 
the service macros). Register 15 must contain the command processor's entry 
point address (found in sce) and register 14 must have the return point address. 
The command processor entry point address is stored in the scecaddr field of the 
sce entry pointed to by the pdbcmda field. 

For example, to pass a command to vtam while running under ost, nnt, or ppt, 
prepare the input described above. Call the NetView command processor identi- 
fied by dsices for your vtam command. 

See sample cnms4280 for an example of calling a command directly. 

Scheduling a Command Using DSIMQS 

Simulating Terminal Input: The simplest way for user-written code to invoke 
regular commands to run under an ost or nnt is to simulate commands entered 
from a terminal. Include the command in the text of a standard buffer with an ini- 
tialized buffer header, as described under "BUFHDR — Buffer Header" on 
page 121. In bufhdr, set hdrmtype to hdrtypet. You may use hdrtypeb as well; 
however, hdrtypeb commands will be neither logged nor echoed. 

Then use macro dsimqs to queue the buffer to the desired ost or nnt, where the 
command will be processed as though it had been entered from a terminal. 



22 NetView Customization: Assembler 



Usually, commands from an operator are scheduled with high priority. This allows 
the command to preempt any existing queued messages or other work that has 
been scheduled at lower priority. Commands scheduled with high priority will also 
preempt command procedures that are already executing. If you do not desire to 
preempt work that may already be queued, including command procedures that 
are already executing, then you should schedule your command at low priority. 
See "DSIMQS — Message Queuing Services" on page 185 for more information on 
priority. 

Building an IFRCODCR: To pass commands to a subtask in the same domain, you 
can build an ifrcodcr and queue it to the desired subtask. An ifrcodcr (see "IFR 
— Internal Function Request" on page 133) is an internal function request (ifr) that 
requests that a command be invoked, ifrcodcr is intended for requesting or con- 
veying data. The command driven by this type of buffer should not present data to 
the operator, neither by full screen nor line mode, and it should not create or 
remove a long running command. These actions could be disruptive because the 
operator could be engaged in unrelated activity. 

The ifr requires an initialized buffer header (bufhdr), a message command exten- 
sion (hdrmcext) if dsimqs bfrflg=yes is specified, and an ifrcode set to ifrcodcr. 
The command and its parameters follow the ifrcode. 

In bufhdr, hdrmleng must reflect the length of the command and its parameters, as 
well as the length of the ifrcode field. Set hdrtdisp to the offset of the ifrcode field. 

HDRMTYPE must be Set tO HDRTYPEI. 

Use macro dsimqs to send the buffer to any subtask that can process a command. 
When the buffer is received, NetView will have increased hdrtdisp by 2 to address 
the command and its parameters. NetView will have decreased hdrmleng by 2, 
because the ifrcode is not included in the command text. 

For more details on the fields and settings of bufhdr and ifr, see "BUFHDR — 
Buffer Header" on page 121 and "IFR — Internal Function Request" on page 133. 

See sample CNMS4283 for an example of scheduling a command. 

Additional Module Services 

Loading and Deleting Modules in Virtual Storage 

Modules which are used infrequently can be dynamically loaded and deleted in 
virtual storage using the dsilod and dsidel macros. Use dsilod to load the module 
and dsidel to delete the module. 

See sample CNMS4271 for an example of using dsilod and dsidel. 

Event Control Block (ECB) Services 

Posting and waiting on Event Control Blocks should be done using the dsipos (post) 
and dsiwat (wait) macros, dsiwat allows waiting on a single ecb or on a list of ecbs. 

See the optional task template (CNMS4277) for an example of waiting on an ecb list. 
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Disk Services 

The disk services macro retrieves data from partitioned data sets (for mvs) or from 
files (for vm). The macro dsidks connects to a data set or filetype, locates a specific 
member or file, and reads the records there, as illustrated in the following 
example: 

DSIDKS SWB=(REG2),DSBW0RD=DISKADDRJYPE=C0NN,NAME=DSIPRF ] 

. ■ i 

DSIDKS SWB*(RE62),DSBW0RD=DISKADDR,TYPE=FIND,NAME=MEMNAME \ 

DSIDKS SWB=(REG2),DSBWGRD=DISKADDRJYPE=READ 

DSIDKS SWB=(REG2),DSBW0RD=DISKADDR,TYPE=READ 

DSIDKS SWB=(REG2) ,DSBWORD=DISKADDR,TYPE=DISC,NAME=DSIPRF 



In the above example, dsidks type = conn initializes the disk service control blocks 
and input buffer, returning the address of the dsb in diskaddr. The ddname is dsiprf 
(for vm, this parameter specifies the filetype, as in name=nccflst). Next, using the 
returned dsbword, dsidks type = find finds the member name memname and reads 
the first record. The next two dsidks type = read instructions read the next two 
sequential records. Finally, dsidks type = disc frees the control blocks and the input 
buffer. 

See sample CNMS4276 for an example of using dsidks to read a NetView initialization 
file. 

Parsing 

NetView command and message buffers (containing the standard NetView bufhdr 
structure) can be parsed using the dsiprs macro. The dsiprs macro requires a 
Parse Descriptor Block (pdb). The size of the pdb can be determined by first 
issuing the dsiprs macro with the pdbsize option specified. This will return the 
required size of the block. After you obtain the storage (from preallocated storage 
or with dsiget), build the control block header (cbh) and set cbhid to the value 
defined by symbol cbhpdb. Set chbtype to zero and store the pdb length in the 
cbhleng field. Then dsiprs can be invoked with the supplied pdb to actually parse 
the buffer, dsiprs will fill in the pdb with the delimiter and parse information. 

See sample CNMS4280 for an example of using dsiprs to calculate the size and ini- 
tialize a parse descriptor block. 

Scope Checking and Parameter Substitution 

The dsikvs (Keyword and Value Service) can be used to determine whether or not a 
particular command keyword and value are defined for this task's Operator Class 
(the opclass statement in the Operator Logon Profile determines the defined oper- 
ator classes). 

The dsipas (Parameter Alias Service) can be used to derive the original 
keyword/value for a command which is entered with parameter aliases. Param- 
eter aliases are defined with the parmsyn statement. See NetView Administration 
Reference. 

See sample CNMS4276for an example of command scope checking. 
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Named Storage 



A storage environment can be easily created and retrieved across multiple 
command processor calls using named storage. 

Macro dsipush can be used to create a named storage pointer, as shown in the fol- 
lowing example: 



L R3,L0CLST0R 

USING SWBLRCPL.R3 

XC G(SWBLRCPU,R3),0(R3) 

MVC SWBLRCLN (4) 9 =A(SWBLRCPU) 

MVC SWBLRCNM(16),MYNAME 

MVC SWBLRCST(4),DYNAST0R 

MVC SWBLRCRE(8),ZER0S 

MVC SWBLRCAB(8),MYABEND 

MVC SWBLRCL6 (8) ,=L ' DS I LRCR8 ' 



BUFFER AREA FOR PUSH LIST 



LENGTH OF PUSH LIST 

UNIQUE NAME OF LRC 

QUEUED STORAGE OBTAINED FOR LRC 

NO RESUME FOR NAMED STORAGE 

ADD ABEND MODULE NAME 



(FOR EXAMPLE) 
SWBLRCFG (FLAGBITS) IGNORED FOR NAMED STORAGE 
L R4,CWBSWB AVAILABLE SWB 

SPACE 3 
DSIPUSH SWB=(R4) ,LIST=(R3),R0LL=NO 



Then macro dsifind can be used to retrieve the named storage pointer, as shown in 
the following example: 



L R3.L0CLST0R 

USING SWBLRCPL,R3 

XC 0(SWBLRCFI,R3),0(R3) 

MVC SWBLRCLN (4) ,=A(SWBLRCFI) 

MVC SWBLRCNM(16),MYNAME 

L R4,CWBSWB 

SPACE 3 
DSIFIND SWB=(R4),LIST=(R3) 
LR R3,R1 
USING MYDSECT.R3 



BUFFER AREA FOR PUSH LIST 



LENGTH OF FIND LIST 

UNIQUE NAME OF LRC 

AVAILABLE SWB 



ADDRESS OF MY NAMED STORAGE 



For more details on the coding of these macros, see "DSIPUSH - Establish Long 
Running Command" on page 202 and "DSIFIND - Find Long Running Command 
Storage" on page 169. For a discussion of long running command processors, see 
"Writing a Long Running Command Processor" on page 64. 

Scheduling Commands in a Cross-Domain Environment 

The dsipss (Presentation Services) macro also provides the ability to schedule 
commands in a cross-domain (ost/nnt) environment: 

You can forward a command from one domain to another by doing either of the fol- 
lowing (providing the route has been previously established via the start domain 
command): 

• Building a buffer with the desired command and issuing macro dsipss with 
type=xsend to transmit the command to the cross-domain task (nnt) in another 
NetView. (The command runs in the other NetView under an nnt.) 
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• Calling the route command. (See "Simulating Terminal Input" on page 22.) 
The route command routes a command to a specified NetView domain. For 
more information, see NetView Operation. 

The commands you invoke can return data to the originating domain by issuing 
dsipss type = output for a buffer with hdrmtype=hdrtypeu or hdrmtype=hdrtypel. 

The maximum length of text that can be sent as a cross-domain command is 240 
bytes, which corresponds to three 80-character input lines. Use multiple com- 
mands to chain data for applications that require larger data transfer. 

Returning a Command to an Originating Domain 

For a command running under an nnt to invoke a command in the originating 
domain, it must issue dsipss type - output for a buffer with hdrmtype=hdrtypex. 
The buffer must contain the desired command verb and parameters. The verb 
must be delimited from the data or parameters by a blank and must be a defined 
command in the receiving domain. 

For example, if data formatting is required, you can build a buffer with 
hdrmtype=hdrtypex and a command in the buffer text. In this case, the command 
verb identifies a user-defined presentation services command processor and the 
parameters are the data to be presented. When the receiver of the ost's cross- 
domain message gets the command buffer, the ost calls the command processor 
with the data. 

Applications are limited to sending 256 bytes of data. Use multiple commands to 
chain data for applications that require larger data transfer. 

Resource Span Checking 

You may want a command processor to use NetView span checking facilities to 
limit operators to particular sets of resources. The following section describes the 
macros and logic required to implement resource span checking. 

The dsirds macro instruction is used to locate an entry address for the resource in 
the authorization and resource table, dsiart. dsirds might be specified as follows: 

DSIRDS SWB=(REG2) ,LUNAME=LUADDR,ARTPOS=ENTRYADR 

For this example, the authorization and resource table (art) entry address for the 
resource pointed to by luaddr will be returned in entryadr. The resource will be 
marked as active. 

Figure 5 on page 27 shows the relationships between the operator identification 
table (oit), the span name table (snt), and art. The relative position of an entry in 
the operator identification table is represented by the bit position of each entry in 
the span name table (n bits). The relative position of an entry in the span name 
table is represented by the bit position of each entry in the authorization and 
resource table (m bits). 

For example, if a user wishes to find whether a particular operator is authorized to 
issue commands for a particular resource, follow this procedure: 

• Use the dsiois macro instruction to find the position of the operator's identifica- 
tion in the oit table. The identification is put in the fullword area pointed to by 
the opid operand of the macro instruction. The relative position is returned to 
the fullword area pointed to by the oitpos operand. 
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• Use the dsisss macro instruction to search the snt for the bit position that cor- 
responds to the location of the operator identification entry in the orr. The bit 
position is specified by the oitpos operand of the macro instruction. It is best 
to begin the search at the beginning of the span name table. The snt address 
(mvtsnt) is found in the NetView main vector table (mvt). Refer to "MVT — 
Main Vector Table" on page 142 in this book. The address of the first span 
entry that corresponds with a bit set to 1 is returned to the fullword area speci- 
fied by the sntaddr operand of the macro instruction. Because it is the address 
of the entry and not its relative position that is returned, the starting address 
should be stored in another area to be used in any calculations that may be 
required to establish the entry's position. 

• Create a mask byte to check the bit position of the authorization and resource 
table (art) that corresponds to the span name table entry position. 

• Use the dsirds macro instruction to find the address of the specific entry for the 
resource. The address of the entry is returned to a fullword area specified by 
the artpos operand of the macro instruction. The resource name is specified 
on the luname operand. 

• Use the mask byte to check whether the corresponding bit is set to 1. 

In the example shown in Figure 5, the dsiois macro can be used to determine the 
position of the identification opid2 in orr. Position 2 is returned to the area specified 
by oitpos. dsisss can then be used to check bit position 2 in snt. The first span 
name with 1 in that position is SPAN2. The address of that entry is returned to the 
area specified by sntaddr. Using the starting address and the address returned, 
and dividing the difference by the length of the snt entries (found (mvtsntln found 
in mvt), the relative position of span2 can be calculated. A mask byte can then be 
prepared to test the bit position corresponding to span2 in art. The dsirds macro 
instruction can then be used to find the address of the resource name in art. If LU2 
is specified in the area pointed to by the luname operand, it is the second entry in 
art. The mask byte can then be used at that location, showing that the operator 
whose identification is opid2 can issue commands for LU2. If a match is not found, 
dsisss can be invoked again to find another span. The starting address specified 
for the sntaddr operand should be the address of the entry immediately following 
span2. This process can be repeated until a span is found or the end of the table is 
reached. 
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DST (Data Service Task) Unique Services 



Access to cnm (Communication Network Management) data and vsam files is pro- 
vided by the dsizcsms (cnm Service) and dsizvsms (vsam Service) macros. These 
macro services can only be used under dsts. dsts and their macro services are 
described fully in Chapter 8 on page 161. 
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Chapter 3. Writing User Exit Routines 



This chapter illustrates how to design, code, and install user exit routines that take 
advantage of the NetView program's exits at strategic processing points. 



Overview of User Exit Routines 



You can write user exit routines to view, delete, or replace data flowing to, from, or 
through NetView. For example, your code can examine the messages passing 
through NetView, record relevant data, and initiate work requests based on the 
data. In addition, your code can delete any unnecessary message from further 
processing or substitute a modified message in place of the original message. 
Thus, user exit routines handle a specific event with non-standard processing and 
automate processes based on message information. 

NetView provides two types of user exits for which you may write routines: 

• Global user exits (DSiExnn), which apply to all NetView tasks. The global user 
exit routines are loaded when NetView starts. See Table 2 on page 32 for a 
list of user exits. 

• dst user exits (xrrnn and bnjpalex), which apply only to dst subtasks. (bnjpalex 
is mvs only.) The dst user exit routines are loaded when the associated dst 
starts. Each dst can have its own set of user exit routines. The bnjpalex exit 
routine runs under the bnjdse36 dst. 

Note: dst user exits should not be used under the Network Product Support (NPS) 
task named dsigds. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 

Each user exit handles a particular event, such as the reception of data from the 
system console. When that event occurs, NetView passes control to the appro- 
priate user exit routine for processing. After processing, the user exit routine 
returns control and passes a return code to NetView. Optionally, up to 10 dst exit 
routines can be concatenated. In this case, the first dst exit routine returns control 
to NetView. If the first exit did not indicate userdrop, NetView then calls the next 
one in the sequence. This process continues until the last dst exit has returned 
control to NetView or userdrop is indicated. 

You do not need to write a routine for each user exit. See "Unused User Exits" on 
page 48 for more information. 
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Table 2. User Exit Environments 



Exit 


Description 


Applicable Tasks 


TVBINXIT 


REENTRANT 


DSIEX01* 


Input from the Operator 


OST with VTAM 
terminal 


On 


Yes 


DSIEX02 


Obsolete; replaced by DSIEX02A 








DSIEX02A 


Message Output this Domain or 
Message Output Cross-Domain 


NNT, OST, PPT 
NNT, OST, 
CNMCSSIR 


On or Off 


Yes 


DSIEX03 


Input Before Command Processing 
HDRTYPEX Cross-Domain Return 
Command Receive 


NNT, OST, PPT 
NNT 


Off 


Yes 


DSIEX04 


Log Output for Buffers not Processed 
by DSIEX02A 


Main Task or Any 
Subtask 


On or Off 


Yes 


DSIEX05 


Before VTAM Command Invocation** 


NNT, OST, PPT 


Off 


Yes 


DSIEX06 


Solicited VTAM Messages** 


NNT, OST, PPT 


Off 


Yes 


DSIEX07 


Cross-Domain Command Send 


NNT, OST 


Off 


Yes 


DSIEX08 


Obsolete 








DSIEX09 


Output to the System Console 


Main Task or Any 
Subtask 


On or Off 


Yes 


DSIEX10 


Input from the System Console 


Main Task 


Off 


No 


DSIEX11 


Unsolicited VTAM Messages** 


PPT 


Off 


No 


DSIEX12 


Logon Validation 


NNT, OST 


Off 


Yes 


DSIEX13 


OST/NNT Message Receiver 


NNT, OST, PPT 


Off 


Yes 


DSIEXU 


Before Logoff 


NNT, OST 


Off 


Yes 


DSIEX16 


Post-Message Automation Table Exit 


NNT, OST.PPT 
CNMCSSIR 


On 


Yes 


BNJPALEX 


Screen 4700 loop alerts 


DST (BNJDSE36) 


Off 


Yes 


XITBN 


BSAM Empty File 


DST 


Off 


No*** 


XITBO 


BSAM Output 


DST 


Off 


No*** 


XITCI 


CNM Interface Input 


DST 


Off 


No*** 


XITCO 


CNM Interface Output 


DST 


Off 


No*** 


XITDI 


DST Initialization 


DST 


Off 


No*** 


XITVI 


VSAM Input 


DST 


Off 


No*** 


XITVN 


VSAM Empty File 


DST 


Off 


No*** 


XITVO 


VSAM Output 


DST 


Off 


No*** 


XITXL 


External Logging 


DST 


Off 


No*** 



Note: 



Does not apply to autotask and mvs console task. 

When using NetView poi only. Does not include messages from mvs/xa ssi. You can process these 

messages in dsiexo2A. 

If used by more than one dst, then they must be reentrant. 



32 NetView Customization: Assembler 



Designing and Coding a User Exit Routine 



Input 



Output 



User exit routines must adhere to the guidelines for user-written programming 
described in "General Coding Guidelines" on page 8. In addition, user exit rou- 
tines must conform to the special requirements described in this section. After 
coding your user exit routine, follow the instructions under "Installing a User Exit 
Routine" on page 48. 



Upon entry to the user exit routine, the registers contain the following information: 

Register Contents 

1 The address of the user exit parameter list (use). The use contains 

the following: 

• The address of a service work block (swb) to be used as a work 
area or to request services from NetView (userswb). If you use 
the swb for your save area or for dynamic variables, you must 
obtain another swb when invoking NetView macros. 

• The address of the message buffer (usermsg) 

• The address of the tvb. 

13 The address of a standard 72-byte save area used to store the 
caller's registers. 

14 The return address. 

15 The entry address of the user exit. 
0, 2 - 12 Unspecified. 



User exit routines pass the following return codes to NetView in register 15 to indi- 
cate that the messages are to be unchanged, deleted, or replaced: 

Return Code Meaning 

userasis (0) Use the message as presented to the user exit; do not delete or 

replace it. 

userdrop (4) Delete the message from the terminal and from the network log, 

system log, and hard copylog; stop processing before the 
message appears on the screen. For more information on how 
to delete messages, see "Deleting Messages" on page 34. 

userswap (8) Replace the message with the message addressed in register 0. 

For more information on how to replace messages, see 
"Replacing Messages" on page 34. 

Do not change any input, particularly the usermsg buffer in the use control block. 
Aside from register 15 (and register if userswap is returned), the other registers 
should be restored without change. See the specific user exit descriptions under 
"Summary of User Exits" on page 36 for additional return code considerations. 
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Deleting Messages 

If you want a message logged but not displayed, you can set the appropriate 
display and logging flags in the ifrcodai (see "IFR — Internal Function Request" on 
page 133) in user exit dsiexcea. 

To delete a message entirely, use return code userdrop. NetView will free the 
message buffers using dsifre. Therefore, the user exit should not free the buffers. 

When NetView receives a userdrop return code, no further exit routines are called. 
Thus, if you have concatenated dst exit routines, a userdrop return code prevents 
the next exit routine from being called. 

When processing a single line of a title-line message, (hdrtypej, hdrtypek, or 
hdrtypel) do not delete a control, label, or end line unless the entire message is 
deleted. When processing a title-line message formatted as an ifrcodai, you may 
delete any line. For example, if dsiexo6 deletes message ist3HI end (only), proc- 
essing of the entire title-line message (of which this is the end line) would be dis- 
rupted. However, if dsiexo2A deletes 1ST3141 end, then the remainder of the title-line 
message would be displayed normally. 

Replacing Messages 

When replacing a message, the new message must either be a static message or 
be in a buffer in a reentrant storage area, such as the swbadatd or swbplist areas 
of the use control block's userswb. Only the text portion of the buffer is swapped. 
Also, make sure that hdrmleng of the new message is less than or equal to 
hdrmleng of the original message. Do not replace a message with a new message 
that is longer, unless the message is formatted as an ifrcodai. 

If you want to replace a title-line message, do not change the hdrmtype or hdrind 
fields in the buffer header. For more information on title-line messages, see "Title- 
Line Output" on page 19. 

When processing a single line of a title-line message (hdrtypej, hdrtypek, or 
hdrtypel), do not replace any lines or the sequence and format may be lost. When 
processing a title-line message formatted as an ifrcodai, you may replace any line. 

User exit dsiexo2A provides a more flexible interface for replacing messages 
including title-line and mlwto (multiline write-to-operator) type messages. See 
"DSIEX02A: Output to the Operator" on page 37. 

You can concatenate dst user exit routines when replacing messages. In this case, 
the buffer containing the replacement message becomes the input for the subse- 
quent dst user exit routine. 

Message Flow and Interception Points 

The following is the sequence of decisions made in handling a message in 
NetView. This information may be useful in determining what forms of message 
processing would be most efficient to meet the performance objectives at your 
installation. 

If a message is suppressed, dropped, or deleted, the message is removed from the 
flow and does not proceed further. 
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OST/NNT Task 

• If the message is solicited from vtam via the poi interface: 

- If this is one of the messages that status monitor uses to update network 
status, it is processed by status monitor. 

- If there is a user exit dsiexo6 (solicited access method message input), the 
exit is invoked. Deleted messages are not processed further. 

• Exit osiexo2A is called (if one exists). If the exit indicates that the message is to 
be dropped, it is deleted. 

• The message is checked to see if it satisfies an &wait condition in a NetView 
command list or a trap condition in a rexx or high-level language command 
procedure. With the suppress option, the message is marked for deletion 
unless DSIEX16 specifies otherwise. 

• Message automation table processing begins. Table actions are reflected in 
the buffer structure given to dsiexi6. 

• dsiexi6 is called. 

The message automation table and dsiexi6 are called only once for each 
unique message in a NetView domain. Any copies of the message made by 
the assign command or the message automation table will not result in a call to 
the message automation table or dsiexi6 in this NetView domain. 

• Logging, display, routing, and command actions are processed as specified in 
the buffer in combination with the current defaults and override settings. 

• If the message is displayed and copies have been assigned by the assign 
command with the copy option, a copy is sent to each assigned operator. The 
copied messages cannot be automated by the message automation table. 

PPT Task Including Messages to the Authorized Receiver 

• If the message is from vtam via the poi interface: 

- If this is one of the messages that the status monitor uses to update 
network status, it is processed by the status monitor. 

- If there is a user exit dsiexh (unsolicited message) or dsiexos (message 
solicited by a vtam command issued under the ppt task), the proper exit is 
invoked. Deleted messages are not processed further. 

- vtam commands and messages received due to the vtam start option 
ppolog=yes (such as those entered from the system console and merely 
echoed to NetView) are logged only. They will not be automated. 

• If the message has been assigned using the assign command with the pri and 
sec options, each assigned operator will be sent a copy of the message. These 
messages then proceed through the ost/nnt flow for those particular operators, 
but the secondary (SEC) copies will not be processed by the message auto- 
mation table or dsiexi6. 

• If the message has not been assigned, it is sent to the authorized message 
receiver and proceeds through the ost/nnt flow for that operator. See the 
NetView Administration Reference for information on how the authorized 
message receiver is determined. 

• If the message has not been assigned and no authorized message receiver is 
logged on to NetView, the flow continues as follows: 
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— Exit dsiexo2a is called (if one exists). If the exit indicates that the message 
is to be dropped, it is deleted. 

— Message automation table processing begins. Table actions are reflected 
in the buffer structure given to dsiexi6. 

— dsiexi6 is called. 

The message automation table and dsiexi6 are called only once for each 
unique message in a NetView domain. Any copies of the message made 
by the assign command or the message automation table will not result in 
a call to the message automation table or dsiexi6 in this NetView domain. 

— Logging, routing, and command actions are processed as specified in the 
buffer in combination with the current defaults and override settings. 

— If the message is to be displayed, it is written to the system console. 



Control Blocks 



The service facilities used in your user exit routine always dictate which control 
blocks you must include in your routine. However, you will always need these 
three control blocks: 

• The user exit parameter list (use) 

• The main vector table (mvt) 

• The service work block (swb). 

Use macro dsicbs to include these and any additional control blocks your routine 
needs. For details, see "DSICBS - Control Block Services" on page 162 and the 
control block descriptions in Chapter 7 on page 119. 

Summary of User Exits 

This section describes each user exit that NetView provides, including examples of 
use and coding requirements. 

DSIEX01: Input from the Operator 

Description: NetView calls dsiexoi when an operator provides standard-mode 
input to an ost or when an nnt receives cross-domain input, dsiexoi runs after 
device-dependent data has been removed from the input buffer but before syntax 
or command verbs are analyzed and before the message is logged. All commands 
issued from the command facility, hardware monitor, or the threshold analysis and 
remote access feature are passed to exit 01. (Hardware monitor and the threshold 
analysis and remote access feature commands have a prefix: "cmd==> or 
cmd=>"). All regular commands, including those from the command facility, hard- 
ware monitor, or the threshold analysis and remote access feature are passed to 
exit 03. 

Example of Use: You can use dsiexoi to count the times an immediate command 
has been called. 

Coding Considerations: dsiexoi follows the coding guidelines given under 
"Restrictions when TVBINXIT is On" on page 9. dsiexoi does not apply to unat- 
tended operator tasks and mvs console operator tasks. 
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DSIEX02: Output to the Operator 

Description: This exit is obsolete. 

DSIEX02A: Output to the Operator 

Description: NetView calls dsiexo2a for standard output to an operator's terminal 
(dsipss type = output, dsipsstype=immed, or flash). dsiexo2a runs before the device- 
dependent output is inserted and before the data is logged. 

The tvbinxit bit in dsitvb indicates the environment in which the user exit routine is 
running. For more information on tvbinxit, see page 8. 

Example of Use: Since the message has been formatted but not yet displayed or 
logged, you can use dsiexo2a to delete or replace the message before it is auto- 
mated, logged, or displayed. 

If your messages will be translated (such as to Kanji), changes to the message text 
may affect the translations. (See NetView Installation and Administration Guide for 
more information.) 

Coding Considerations: If tvbinxit is on, dsiexo2a follows the coding guidelines 
given under "Restrictions when TVBINXIT is On" on page 9. 

Do not use macro dsipss in this user exit routine. If a message is required, use 
dsimqs to queue the message to the subtask. 

Since NetView does not check the syntax of messages that are sent to a terminal, 
dsiexo2A does not receive a parse descriptor block (pdb). 

Message automation is invoked after this exit routine has been called; therefore, 
any changes made for messages in this user exit may affect message automation. 
Message automation is not invoked for a message that has been deleted by this 
exit routine. 

dsiexo2a provides the following additional features not available in other exits: 

• The NetView buffer passed to this exit is an ifrcodai internal function request. 
You will need to reference the ifr control block rather than the bufhdr. 

• For single line messages, multiple line messages, and title-line messages, this 
buffer points to the entire chain of buffers that comprise the message. 

All chained buffers can be replaced by using osiGETfor non-queued subpool zero 
storage for new buffers and copying or replacing all the data in the old buffers. 
Any original buffers passed to the exit should be either freed or passed back to 
NetView on the return. The unused buffers must be freed using dsifre for non- 
queued subpool zero storage. You must be careful to initialize all necessary fields 
in all buffers and copy any reserved or unused header information from each of the 
buffers. (The ifrcodai buffer should not be freed.) 

Note: NetView will free all returned buffers that are in the ifrcodai format. 

The ifrcodai contains control information and mvs system data which should only 
be accessed through the provided NetView message table and command list inter- 
faces. Unauthorized modification of these fields may cause processing, logging, or 
display loops. 

Under mvs/xa, dsiexo2A is supported only in 31-bit addressing mode. 
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Return Code Considerations: 
Return Code Meaning 



USERDROP 



USERSWAP 



USERASIS 



NetView will free all of the buffers passed to the exit. Thus dsiexo2a 
should not dsifre the buffers when using userdrop. Buffers to be 
freed by NetView are pointed to by usermsg. 

NetView requires register to point to the original buffer that was 
passed to the user exit. If the buffer chain is modified, pointers 
within the buffers that are used for chaining purposes will also 
have to be changed (such as ifrautba, ifrautbl. and hdrnextm). 
You must free any data buffers you remove from the ifrautba 
chain. NetView will free all returned buffers based upon the 
address in register 0, including the ifrcodai buffer. 

NetView uses and frees the original buffers using usermsg. 



Note: userswap is identical in function to userasis except that register is used 
instead of usermsg to find the buffers. 

DSIEX03: Input Before Command Processing 

Description: All regular commands call dsiexo3. This type of command includes 
the following: 

Commands issued by a command procedure 

Commands received from another subtask 

Commands used to start the hard-copy log at logon 

Commands used as the initial command 

Commands resulting from the message automation table 

Commands entered for an mvs console operator task 

Commands entered from a terminal 

Commands received as hdrtypex messages from an nnt 

Commands queued with excmd. 

Before running, all commands are passed to either dsiexoi or dsiexo3. Immediate 
commands are passed to dsiexoi. Regular commands entered from a command 
facility, threshold analysis and remote access feature or hardware monitor screen 
are passed to dsiexoi and dsiexo3. The remaining command types previously listed 
are passed to dsiexo3. 

Example of Use: You can use dsiexo3 to restrict usage of particular, regular com- 
mands if your conditions are more complex than those provided by scope 
checking. 

Coding Considerations: None. 

DSIEX04: Log Output 

Description: NetView calls dsiexo4 during the logging and tracing processes. 
DSIEX04 is located within log services and applies to messages logged on the 
network log, the external trace log, the mvs system log, and the hard-copy log. It 
runs before the message is reformatted and sent to the log. 

DSIEX04 is not called if dsiexo2a is called since logging options may be specified 
either in dsiexo2a or in the message automation table. dsiexo4 is called only if the 
dsiwls macro is issued from other than a dsipss request. 
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Example of Use: You can use dsiexo4 to edit information sent to the network log, to 
the mvs system log, or to the hard-copy log. You can send certain messages to a 
specific log or to no log at all. 

Coding Considerations: If tvbinxit is on, dsiexcw follows the coding guidelines 
given under "Restrictions when TVBINXIT is On" on page 9. 

Do not use macro dsiwcs or dsiwls in this user exit routine. 

Since dsiexw can run under any subtask that issues macro dsiwls, be sure that any 
service facilities you request are supported by the subtask under which the routine 
is running. For example, the dst subtask is restricted to vsam or cnm interface ser- 
vices. 

Since NetView does not check the syntax of messages that are sent to a log, dsiexcm 
does not receive a parse descriptor block (pdb). See "PDB — Parse Descriptor 
Block" on page 146, if you wish to parse the messages in dsiexo4. 

Return Code Considerations: dsiexo4 may pass four other return codes in addition 

tO USERASIS. USERDROP, and USERSWAP. 

Return Code Meaning 

userlog Write the message to the network or mvs system log only. 

userlogr Write the substituted message to the network or mvs system log 

only. The address of the buffer containing the new message is in 
register 0. 

userhcl Write the message to the hard-copy log only. 

userhclr Write the substituted message to the hard-copy log only. The 

address of the buffer containing the new message is in register 0. 

DSIEX05: Before VTAM Command Invocation 

Description: NetView calls dsiexos when preparing to pass a command to vtam via 
the poi interface; domain qualifiers have been removed and all span checking has 
been completed. 

Example of Use: You can use dsiexos to verify that an operator is authorized to 
issue a particular command. 

Coding Considerations: Code the routine to handle both the ost and ppt control 
block structures. 

This exit applies only to commands entered directly (not using the 'MVS' prefix) 
that are passed through NetView's poi. 

Note: Commands passed to dsiexos have already been processed under dsiexo3 
(and, perhaps, dsiexoi). 

DSIEX06: Solicited VTAM Messages 

Description: NetView calls dsiexos when it receives a solicited vtam message via 
the poi interface, which is generated in response to a vtam command the user 
issued or the ppt issued. The message has not yet been processed or logged. 

Example of Use: You can use dsiexo6 to change the message number or text of a 
vtam message or to process vtam messages. 
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Coding Considerations: Code the routine to handle both the ost and ppt control 
block structures. 

This exit applies only to messages received through NetView's poi in response to 
commands entered directly (not using the 'MVS' prefix). 

Message automation is invoked after this exit routine has been called; therefore, 
any changes made for messages in this user exit may affect message automation. 
Message automation is not invoked for a message that has been deleted by this 
exit routine. 

Note: Messages processed (and not dropped) by dsiexo6 will subsequently be 
processed by dsiexo2a. 

DSIEX07: Cross-Domain Command Send 

Description: NetView calls dsiexoz before commands are sent cross-domain to an 

NNT (DS1PSSTYPE = XSEND). 

Example of Use: You can use dsiexo7 to monitor cross-domain traffic through the 
network. 

Coding Considerations: Do not use dsipsstype=xsend in this user exit routine. 
Also, avoid directly calling commands that route a command to another domain, 
such as route, display, or vary. If necessary, you may queue such commands for 
execution (see "Simulating Terminal Input" on page 22 and "Building an 
IFRCODCR" on page 23). 

dsiexo7 does not receive a pdb. The cross-domain NetView parses the messages 
after they are received. See "PDB — Parse Descriptor Block" on page 146, if you 
wish to parse the messages in dsiexoz. 

DSIEX08: Cross-Domain Message Receive 

Description: This exit is obsolete. 

Migration Considerations: Rewrite code into dsiexo3 and dsiexo2A using hdrdomio 
to identify commands and messages received from other domains. 

DSIEX09: Output to the System Console 

Description: NetView calls dsiexo9 when a message is written to the system 
console operator using macro dsiwcs. The message has not been formatted for 
transmission. 

Example of Use: You can use dsiexo9 to edit messages sent to the system console. 

Coding Considerations: If tvbinxit is on, dsiexo9 follows the coding guidelines 
given under "Restrictions when TVBINXIT is On" on page 9. 

dsiexo9 is called as a result of dsiwcs macro calls. The output of the mvs console 
operator task (ost) is processed in dsiexcka instead of dsiexo9. 

Do not use macros dsiwcs or dsimqs in this user exit routine. If you need to send a 
message to the system console from this exit routine, use system macros instead. 

Since NetView does not check the syntax of messages that are sent to the system 
console, dsiexo9 does not receive a parse descriptor block (pdb). See "PDB — 
Parse Descriptor Block" on page 146, if you wish to parse the messages in dsiexo9. 
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DSIEX10: Input from the System Console 

Description: NetView calls dsiexio when input is received from the system console 
operator. The exit is called after the command has been entered but before it is 
invoked or logged. 

Example of Use: You can use dsiexio to allow the system console operator to 
enter command abbreviations and synonyms. These could then be expanded in 
the user exit routine. 

Coding Considerations: dsiexio can only be called from the main task, not from a 
subtask. 

dsiexio does not receive a parse descriptor block (pdb). See "PDB — Parse 
Descriptor Block" on page 146, if you wish to parse the messages in dsiexio. 

dsiexio is not called for commands entered by an operator using an mvs console 
operator task (ost). dsiexo3 is called instead. 

DSIEX11: Unsolicited VTAM Messages 

Description: NetView calls dsiexh when an unsolicited vtam message is received 
via the poi interface. In addition, when vtam's ppolog=yes modify or start option is 
used, copies are presented to dsiexh. This user exit is called before the resource 
name is analyzed and before the message is logged. 

Example of Use: dsiexh can issue macro dsimqs to send a copy of the message 
buffer prior to processing by NetView. If you want to send unsolicited messages to 
all operators, dsiexh can transform the messages into msg all commands. 

Coding Considerations: If dsiexh calls a command or a command procedure, the 
command restrictions for the ppt apply. 

Message automation is invoked after this exit routine has been called; therefore, 
any changes made for messages in this user exit can affect message automation. 
Message automation will not be invoked for a message that has been deleted by 
this exit routine. 

DSIEX12: Logon Validation 

Description: NetView calls DSIEX12 at the completion of the logon process, after the 
logon has been accepted by NetView. 

Example of Use: You can use DSIEX12 to perform additional checking of authori- 
zation and environmental customization. DSIEX12 can also send messages to other 
operators. 

Coding Considerations: If output to the screen is required, use only the following 

DSIPSS TYPES: SCRSIZE, WINDOW, ASYPANEL, CANCEL, PSSWAIT, and TESTWAIT. 

Return Code Considerations: If the user exit routine issues a return code of zero, 
the logon proceeds. If specified, your hard-copy log starts and the initial command 
runs. If the issued return code is nonzero, the operator is logged off. 

This exit is called under all ost and nnt tasks including unattended-operator and 
mvs- console-operator tasks. 
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DSIEX13: OST/NNT Message Receiver 

Description: NetView calls dsiexi3 when either a message buffer or a user-defined 
internal function request (ifrcodus) is received through macro dsimqs. dsiexi3 is 
called within the message receiver for subtask-subtask communication. A 
message buffer is any non-HDRTYPEi (ifr) buffer. 

Example of Use: You can use dsiexis in conjunction with ifrcodus to initiate a user 
function with a buffer. Code dsiexi3 to perform the user function specified by 

IFRCODUS. 

Coding Considerations: None. 

Return Code Considerations: When DSIEX13 returns, these buffers are written to the 
operator terminal with dsipss type = output, unless return code 4 is issued. The 
messages are logged after user exit dsiexo2A is called. 

DSIEX14: Before Logoff 

Description: NetView calls dsiexu when an ost or nnt subtask is preparing to end 
for any of these reasons: 

• If logoff is entered at the operator's terminal 

• If the subtask losterm exit is driven (vtam) 

• If the subtask is posted to terminate. 

The subtask cannot communicate with the operator's terminal at this point. It is 
possible, however, to issue macro dsiwcs to write to the system console and macro 
dsiwls to write entries to the log. 

Example of Use: You can use dsiexu to save accounting information or update 
tables. 

Coding Considerations: Because there is no buffer associated with logoff proc- 
essing, dsiexu receives neither an input buffer nor a pdb. 

Return Code Considerations: NetView ignores any return code received from this 
user exit routine. 

DSIEX16: Post-Message Automation Table Exit 

Description: NetView calls dsiexi6 immediately after a message has been consid- 
ered for automation under the display services (dsipss) of NetView. dsiexi6 can be 
run under the ost, nnt, ppt, or cnmcssir task. It receives a description of the total 
processing to be performed on the message. This exit is called just before logging, 
display, routing, or command actions are processed. This exit is not called for 
messages that are deleted by dsiexo2a. However, this exit is called for messages 
that are suppressed by &wait, trap and suppress, or the automation table. Message 
automation table processing occurs before dsiexi6 is called, and the resultant 
actions are scheduled immediately after this exit. 

Example of Use: You can use this exit to modify the processing options for the 
message and specify or substitute new logging, display, command, or routing 
actions independently of one another. 

This exit can reformat messages by removing buffers, changing buffers, and 
adding entirely new buffers to the original message. This exit can prevent override 
command options from taking effect for messages. This exit can also help monitor 
the effectiveness of message suppression and automation. 
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Coding Considerations: tvbinxit will be on when called for dsipsstype=immed. For 
more information see "Restrictions when TVBINXIT is On" on page 9. Do not use 
dsipss in this exit routine. New messages may be issued by chaining them to the 
original message structure. dsiexi6 does not receive a parse descriptor block. 
DSIEX16 uses the ifrcodai internal function request similar to dsiexo2A. 

NetView uses the usermsg field on return as the chain of ifrcodai structures to be 
processed, if usermsg is set to zero by dsiexi6, the user exit must free all buffers 
passed. These buffers are non-queued, subpool-zero storage. The buffers are 
31-bit mode only for mvs/xa. When usermsg is non-zero, it must point to the chain 
of ifrcodai buffers. 

Return Code Considerations: DSIEX16 does not require the use of register 15 return 
codes. Buffer deletion is indicated by setting usermsg to zero after freeing any 
remaining buffers. Buffer substitution is done by manipulating the buffer structures 
dynamically. 

BNJPALEX: Alert Generation Exit Routine 

Description: When bnjpalex is given control, register 1 points to a single element 
parameter list that points to the following data structure: 

AL4 Address of the first extended statistical counter 

AL4 Address of an 8-byte user text area 

AL4 Address of the first extended statistical counter 

AL4 Address of an 8-byte user text area 

CL8 Controller name 

XL8 Extended statistical counter threshold exceeded bit map (nth bit on indicates 

that the nth extended statistical counter exceeded the threshold) 

XL2 |_ 00 p Basic Counter 2 threshold 

XL2 Extended statistical counter threshold 

XL1 Loop Basic Counter 2 counter value 

XL1 Count of extended counters reported (maximum 64) 

cli Alert type byte 

X'01 ' Extended statistical counter(s) exceed threshold. 

X'02 1 Loop Basic counter exceeds threshold. 

X'03 1 Both counter types exceed thresholds. 

When bnjpalex returns control to the 4700 support facility, register 15 return codes 
indicate what is to be done with the alert. The following are the only permissible 
values for register 15: 

Issue the alert. 

4 issue the alert and include the eight bytes of user text located in the user text 
area. 

8 Do not issue the alert. 

Coding Considerations: Each time the 4700 support facility receives data from the 
4700 network, it analyzes that data with respect to user-defined error thresholds. 
Whenever a threshold is exceeded, the 4700 support facility issues an alert 
message to the NetView authorized receiver. A program exit is provided by the 
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4700 support facility for screening the loop error alerts (either Loop Basic Counter 
2 or extended statistical counter alerts). The optional user-written exit routine may 
add up to eight bytes of user text in the alert message or it may completely sup- 
press the alert. 

If the exit is to be included in the system, it must be linked into a load library speci- 
fied in the steplib of the NetView start procedure. The name of the load module as 
well as it's entry point must be bnjpalex. The exit must be written as a reentrant 

CSECT. 

If bnjpalex has not been coded, whenever the bnjdse36 task is started, a message 
(IEA703I for mvs/xa) will be displayed indicating the load has failed. In this case, the 
issuance of the IEA703I (for mvs/xa) message is normal. 

For an example of an exit routine see IBM 3600/4700 Threshold Analysis and 
Remote Access Feature Installation and Customization Guide. 

XITBN: BSAM Empty File 

Description: The dst calls xitbn if the dst encounters a bsam open failure because 
of an empty data set or file. 

Example of Use: You can use xitbn to place a record in the empty data set. You 
should code this user exit only if you wish to write your own bsam subtask using dst 
as a base. 

Coding Considerations: xitbn can only use the service facilities available to the 
dst subtask, excluding macros dsizvsms and dsizcsms. 

Return Code Considerations: To initialize the bsam data set or file, return the 
userswap return code and have register point to a buffer that contains the record 
to be used. A return code other than userswap causes the dst to end. 

XITBO: BSAM Output 

Description: The dst calls xitbo immediately before the record is written to the 
bsam data base. 

Example of Use: You can use xitbo to modify the record before it is sent to the 
bsam data set or file. 

Coding Considerations: xitbo can only use the service facilities available to the 
dst subtask, excluding macros dsizvsms and dsizcsms. 

You should avoid coding user exits for frequently executed functions, such as bsam 
i/o, since performance can be degraded significantly. 

XITCI: CNM Interface Input 

Description: The dst calls xitci after cnm data is received. 

Example of Use: You can use xitci to modify cnm interface input data (Deliver ru). 

Coding Considerations: xitci can only use the service facilities available to the dst 
subtask, excluding macros dsizvsms and dsizcsms. 

Unsolicited cross-domain alerts can cause this user exit to gain control. To deter- 
mine if the alert came from the local cnmi or the distributed host cnmi, the user exit 
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should check the dsrbcpms flag. If dsrbcpms is on, the alert was generated from 
the distributed host cnmi. 

If a substitute buffer is returned in register 0, the data must be a valid SNA request 
unit (ru). See Systems Network Architecture Product Formats for a discussion of 
ru formats. 

xitci invoked under the dsicrtr subtask allows access to unsolicited cnm data prior 
to NetView routing (except for cross-domain alerts, which are only accessible 
under the bnjdserv subtask). xitci invoked under any other dst will allow access to 
cnmi data (both solicited and unsolicited) peculiar to that dst. For example, if an 
xitci exit is specified for the bnjdserv dst, it would be invoked for any solicited or 
unsolicited data that the hardware monitor processes. 

For cross-domain alerts, the dsrbcpms bit should not be turned off by the user exit. 
Upon entry to the user exit, hdrtdisp is the offset to the focal point transfer ru 
Header (nmvt follows the header, for a mapping of this header, please refer to the 
control block section), hdrmleng is set to the length of the ru header plus the 
length of the nmvt. If a substitute buffer is returned, it should be a valid nmvt and 
only the nmvt data area can be changed. The ru header must remain and the user 
must copy the ru header into his buffer. The hdrtdisp of the user buffer should be 
the offset to the ru header and hdrmleng should be the length of the ru header (44 
bytes) plus the length of the new nmvt. The length of the new nmvt cannot exceed 
the original nmvt, else truncation results. NetView does not recommend substi- 
tution of cross-domain alert buffers. 



Network Services Request Units are routed as follows: 



Request 


Header Value 


Responsible Subtask Name 


RECMS 


X'010381' 


BNJDSERV 


RECFMS 


X'410384' 


bnjdserv and AAUTSKLP 


ROUTE-INOP 


X'410289' 


AAUTSKLP 


CNM 


X'810814* 


AAUTSKLP 


NMVT 


X'41038D' 


As follows 



nmvt Request Units are routed based upon the Major Vector Key: 
Major Vector Responsible Subtask 



Key 


Name 


X'OOOO' 


BNJDSERV 


x'ooor 


BNJDSERV 


X'0010' 


AAUTSKLP 


X'0025* 


BNJDSERV 


X'006F 


DSIGDS 
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X'0080" AAUTSKLP 

X'-|3FF' BNJDSERV 



XITCO: CNM Interface Output 

Description: The dst calls xitco prior to a request for cnm interface output. 

Example of Use: You can use xitco to modify the request for cnm data (Forward 

RU). 

Coding Considerations: xitco can only use the service facilities available to the 
dst subtask, excluding macros dsizvsms and dsizcsms. 

If a substitute buffer is returned in register 0, the data must be a valid sna request 
unit (ru). See Systems Network Architecture Technical Overview for a discussion 
of ru formats. 

XITDI: Data Services Task (DST) Initialization 

Description: The dst calls xitdi for each statement read by the dst during initializa- 
tion. When end-of-file is reached, this user exit is entered and two dsiuse fields, 
usermsg and userpdb, are set to zero indicating that there is no more data. You 
can code up to 10 module names for each user-written exit routine. See NetView 
Administration Reference for more information on xitdi during dst initialization. 
Also see "Data Services Task (DST)" on page 86. 

Example of Use: You can add xitdi to the dst initialization deck to provide user 
initialization values to dst initialization. 

Coding Considerations: xitdi can only use the service facilities available to the dst 
subtask, excluding macros dsizvsms and dsizcsms. xitdi should not refer to dsrb 
fields. 

Note: If all initialization data is to be processed by xitdi, specify the dst initializa- 
tion statement that identifies xitdi as the first statement in the dst initialization 
member. 

Return Code Considerations: xitdi can prevent the dst from processing a defi- 
nition statement by passing return code userdrop (4) in register 15. 

When called for an end-of-file situation, a nonzero return code in register 15 indi- 
cates that the dst should be stopped. 

XITVI: VSAM Input 

Description: The dst calls xrrvi after a dsizvsms macro is issued. The record has 
been read from the vsam data base, but it is not yet passed to the requesting data 
services command processor. 

Example of Use: You can use xrrvi to modify the record after it has been retrieved 
from a vsam data set or file. 

Coding Considerations: xitvi can only use the service facilities available to the dst 
subtask, excluding macros dsizvsms and dsizcsms. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 
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XITVN: VSAM Empty File 

Description: The dst calls xitvn if the dst encounters a vsam open failure because 
of an empty data set or file. 

Example of Use: You can use xitvn to place a record in the empty data set. 
NetView provides its own xitvn for vsam logs generated under dst. You should 
code this user exit only if you wish to write your own vsam subtask using dst as a 
base. 

Coding Considerations: xitvn can only use the service facilities available to the 
dst subtask, excluding macros dsizvsms and dsizcsms. 

Notes: 

1. Only vsam key-sequenced data sets (ksds) are supported. 

2. Do not replace NetView provided xitvn exits for the dsilog and dsitrace sub- 
tasks. 

Return Code Considerations: To initialize the vsam data set or file, return the 
userswap return code and have register point to a buffer that contains the record 
to be used. A return code other than userswap causes the dst to end. 

XITVO: VSAM Output 

Description: The dst calls xitvo immediately before the record is written to the 
vsam data base. 

Example of Use: You can use xitvo to modify the record before it is sent to the 
vsam data set or file. 

Coding Considerations: xitvo can only use the service facilities available to the 
dst subtask, excluding macros dsizvsms and dsizcsms. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 

XITXL: External Logging 

Description: The dst calls xitxl whenever data is to be sent to an external log 
using dsiwls with the extlog parameter. For example, session monitor performs 
external logging of response time and configuration data. 

Example of Use: For vm, you can use xitxl to perform the actual logging, since smf 
is not available. 

Coding Considerations: xitxl can only use the service facilities available to the 
dst subtask. The buffer passed to the user exit contains the standard header, with 
hdrtdisp pointing to control block dsielb. The data that is to be logged follows 
dsielb. 

Return Code Considerations: For mvs with smf, the return codes are standard. For 
mvs without smf and for all other operating systems, NetView ignores the return 
code and performs no further processing. 
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Unused user Exits 

NetView attempts to load the global exits (DSiExnn) and the dst exits (xrrnn) speci- 
fied with dstinit statements. If a load attempt fails, NetView issues this message: 



ns 



DSI09GI LOAD FAILED FOR NCCF MODULE exitname 



If you prefer not to receive this message, you may write a routine for the unused 
user exit as shown below. However, since null exits slow performance, do not 
create them (exits dsiexo2a and DSIEX16 are the exception). A null dsiex02a or DSIEX16 
does not degrade performance since no 31- to 24-bit address conversion is done. 



exitname 


CSECT 








SLR 


15, 


,15 




BR 


14 






END 







Installing a User Exit Routine 



Link-edit the user exit routine load module into the NetView load library. For 
global user exits, use the appropriate DSiExnn name. For dst user exits, use a 
name that you select. Use only one load module for each routine; conditional 
selection at exit time is not allowed. 

Global user exit routines are automatically loaded when NetView starts, dst user 
exit routines are loaded when the dst starts, provided they have been specified in 
the dstinit statement. 

See "Preparing Your Code for Use" on page 4 for information on testing your exit 
routine before use. 



Template for a User Exit Routine 



Figure 6 on page 49 shows the basic structure of a user exit routine, including 
standard entry and exit linkage. This template will run as written for any of the 
NetView user exits; however, it will perform no functions until you add your code at 
the designated place in the template, it is available online in the NetView sample 
library (Syslcnmsamp) as CNMS4282. 
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ATMPUXIT CSECT 
******************************************************* 

* * 

* IEBCOPY SELECT MEMBER* ((CNMS4282, ATMPUXIT, R)) * 

* * 

* MODULE NAME: * 

* * 

* FUNCTION: * 

* * 

* * 

* INSTALLATION: * 



* INPUT: REG 1 - ADDRESS OF USER SERVICE BLOCK (DSIUSE) * 

* REG13 - ADDRESS OF CALLER'S SAVE AREA * 

* REG14 - RETURN ADDRESS * 

* REG15 - ENTRY ADDRESS * 

* * 

* OUTPUT: * 

* * 

* REGISTERS: * 

* REG - WILL CONTAIN ADDRESS OF USER SWAP BUFFER IF * 

* USERSWAP RETURN CODE USED, ELSE RESTORED * 

* REG 1 - REG14 - RESTORED UPON RETURN * 

* * 

* REG 15 RETURN CODES: * 

* USERASIS (0) - OK, CONTINUE PROCESSING * 

* USERDROP (4) - DELETE DATA BUFFER AND END * 

* PROCESSING * 

* USERSWAP (8) - SWAP BUFFER SUPPLIED BY REG * 

* AND CONTINUE PROCESSING * 

* * 

* NETVIEW MACROS: * 

* * 

* DSICBS - CONTROL BLOCK SERVICE * 

* * 

*********************************************************************** 



PROLOG 



USING *,15 




B PROLOG 




DC C ATMPUXIT 


&SYSDATE. at &SYSTIME.* 


DS OH 




STM 14,12,12(13) 


SAVE REGISTERS 


DROP 15 




LR 12,15 


SAVE BASE REGISTER 


USING ATMPUXIT, 12 


REG 12 IS THE BASE 


USING DSIUSE, 1 


REG 1 POINTS TO DSIUSE 


L ll.USERSWB 


LOAD REG 11 WITH SWB ADDRESS 


USING DSISWB.ll 


BASE SWB 


LA 2.SWBSAVEA 


GET ADDRESS IF SAVE AREA 


ST 2,8(,13) 


SAVE REG 2 


ST 13,4(,2) 


SAVE REG 13 


LR 13,2 


REG 13 CONTAINS SAVE AREA ADDR 


LR 9,1 


MOVE DSIUSE ADDRESS 



Figure 6 (Part 1 of 4). Template for a User Exit Routine 
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DROP 1 DROP ORIGINAL BASE 

USING DSIUSE.9 REG 9 POINTS TO DSIUSE 

L lO.USERPDB LOAD REG 10 WITH PDB ADDR 

USING DSIPDB.10 BASE THE PDB 

L 8.USERTVB ADDRESS THE TVB 

USING DSITVB.8 BASE THE TVB 

L 7.TVBMVT GET THE ADDRESS OF THE MVT 

USING DSIMVT.7 BASE THE MVT 

*********************************************************** 

* * 

* NOW OBTAIN ANOTHER SWB IN ORDER TO ISSUE NETVIEW SERVICE MACROS * 

* * 

*********************************************************************** 

DSILCS CBADDR=MYSWBPTR,SWB=GET GET A NEW SWB 
SPACE 1 

* NOTE: SEE DSISWB DSECT AT THE END OF THE LISTING 

SPACE 1 

LTR 15,15 TEST DSILCS RETURN CODE 

BNZ ASIS Simply Return 

* (Alternatively design and perform 

* some user notification) 
L 5, MYSWBPTR POINT TO NEW SWB 

L 4.TVBTIB PUT THE TIB ADDRESS IN REG 4 

ST 4,SWBTIB-DSISWB(,5) STORE MY TIB ADDR IN THE NEW SWB 
*********************************************************************** 

* * 

* THIS NEW SWB (MYSWBPTR) SHOULD BE USED FOR SERVICE MACROS. * 

* * 

*********************************************************************** 

* PUT YOUR USER EXIT CODE HERE * 



BAL 14.FREESWB Free the MYSWBPTR SWB 

* * 

* Branch to return processing you require (ASIS, DROP, or SWAP)* 
*********************************************************************** 

* PICK THE EXIT LINKAGE DESIRED FROM THE THREE BELOW: 
*********************************************************************** 

* __ __ „_ _„ 

* ASIS: TO PROCESS THE BUFFER AS IT IS FROM HERE ON, RETURN FROM HERE 

*___ 

ASIS LA 15.USERASIS SET AN ASIS RETURN CODE 

RESTORE CALLER'S SAVE AREA ADDR 
RESTORE CALLER'S REGISTER 14 
RESTORE CALLER'S REGISTERS 0-12 
RETURN TO CALLER 

DROP: TO STOP FURTHER PROCESSING ON THIS BUFFER, RETURN FROM HERE 

DROP LA 15.USERDR0P SET A DROP RETURN CODE 

RESTORE CALLER'S SAVE AREA ADDR 
RESTORE CALLER'S REGISTER 14 
RESTORE CALLER'S REGISTERS 0-12 
RETURN TO CALLER 



LA 


15.USERASIS 


L 


13,4(,13) 


L 


14,12(,13) 


LM 


0,12,20(13) 


BR 


14 



LA 


15.USERDR0P 


L 


13,4(,13) 


L 


14,12(,13) 


LM 


0,12,20(13) 


BR 


14 



SPACE 1 



Figure 6 (Part 2 of 4). Template for a User Exit Routine 
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LA 


15.USERSWAP 


L 


O.SWAPBFR 


L 


13.4(,13) 


L 


14.12(,13) 


LM 


1,12,24(13) 


BR 


14 



* SWAP: TO SWAP A BUFFER FOR THE BUFFER PASSED, RETURN FROM HERE 

*__ ________ 

SWAP LA 15.USERSWAP SET A SWAP RETURN CODE 

POINT TO THE SWAP BUFFER 

RESTORE CALLER'S SAVE AREA ADDR 

RESTORE CALLER'S REGISTER 14 

RESTORE CALLER'S REGISTERS 1-12 

RETURN TO CALLER 

SPACE 1 
******************************************************** 

* Subroutine: FREESWB 

* Function: Free the SWB addressed by MYSWBPTR 

* Note: The new SWB must be released before exiting 
*********************************************************************** 

FREESWB EQU * 

ST 14.SAVE14 Save caller's return address 

DSILCS CBADDR=MYSWBPTR,SWB=FREE NOW FREE THE GOTTEN SWB 

* No recovery for failure can be made 
L 14.SAVE14 

BR 14 Return to call point 

Figure 6 (Part 3 of 4). Template for a User Exit Routine 
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************************************************************** 

* Declares and DSECTs 

*********************************************************************** 

control blocks 

DSIMVT,DSISWB,DSIPDB,DSIUSE,DSISVL, * 

Suppress Control Block Listing 



* 


Include the required 




DSICBS DSITIB.DSITVB, 






PRINT=NO 


RQ 


EQU 





Rl 


EQU 


1 


R2 


EQU 


2 


R3 


EQU 


3 


R4 


EQU 


4 


R5 


EQU 


5 


R6 


EQU 


6 


R7 


EQU 


7 


R8 


EQU 


8 


R9 


EQU 


9 


R10 


EQU 


10 


Rll 


EQU 


11 


R12 


EQU 


12 


R13 


EQU 


13 


R14 


EQU 


14 


R15 


EQU 


15 


DSISWB 


DSECT 


9 




ORG 


SWBADATD 


WORKAREA DS 


0CL256 


MYSWBPTR 


DS 


A 


SWAPBFR 


DS 


A 


SAVE14 


DS 


A 




SPACE 


1 


ATMPUXIT 


CSECT 


» 




END 


ATMPUXIT 



EXTEND THE SWB DEFINITION 
POINT TO 256 BYTE WORK AREA 
WORKAREA IS 256 BYTES LONG 
ADDRESS OF MY NEW SWB SAVED HERE 
ADDRESS OF SUBSTITUTION BUFFER 
Save area for Register 14 

RESUME CSECT 

END OF THE USER EXIT 



Figure 6 (Part 4 of 4). Template for a User Exit Routine 
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Chapter 4. Writing Command Processors in Assembler 
Language 

This chapter illustrates how to design, code and install assembler language 
command processors for NetView. Command processors perform a particular 
service or function, such as extracting relevant data from a control block and pre- 
senting the data to an operator. 

Overview of Command Processors 

Command processors run in any of several execution environments, as allowed by 
the command processor's type, defined by the cmdmdl statement in dsicmd. The 
cmdmdl statement identifies the command processor as one of the following types: 

• Regular commands (type = r) 

• Immediate commands (type= i) 

• Data services commands (type=d) 

• Regular and immediate commands, combined (type=b) 

• Regular and data services commands, combined (type = rd). 

In addition, long running commands are composed of regular (or type rd or 
type b) commands. Parts of long running commands are coupled by their internal 
processing. 

Regular Command Processors 

A regular command runs under the ost, nnt, or ppt subtask environments and 
receives control with the tvbinxit bit set off. This means that the processing of a 
regular command may be interrupted by the NetView program's system and vtam's 
exit routines, as well as by immediate command processors. 

For specific coding instructions, see "Writing a Full-Screen Command Processor" 
on page 61 and "Writing a Long Running Command Processor" on page 64. 

Immediate Command Processors 

An immediate command runs under the ost and nnt subtask environments. Unlike 
regular commands, immediate commands receive control with the tvbinxit bit set 
on. This means that they interrupt mainline processing and cannot be interrupted 
by another command. 

An immediate command starts processing as soon as an operator enters the 
command, regardless of any regular command currently running. Thus the 
requested function is performed at once, even if the task is in the middle of a large 
queue of work. 

Data Services Command Processors 

A data services command processor (dscp) runs under the dst subtask environ- 
ment, dscps perform cnm data services using macro dsizcsms, or vsam data ser- 
vices using macro dsizvsms, or both services, dscps are also appropriate for 
centralized or serialized user-defined functions that do not use cnm or vsam ser- 
vices. See "Data Services Command Processor" on page 88 for details. 
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Combination Command Processors 

One type of combination command processor runs as a regular or immediate 
command, depending on its environment. This command processor checks the 
tvbinxit bit and processes the command as an immediate command if the bit is on 
or as a regular command if the bit is off. 

Another type of combination command processor runs as a regular or data ser- 
vices command, depending on the task type indicated in the tvb. If the task type is 
dst, the command runs as a data services command. Otherwise, the command 
runs as a regular command. 

Long Running Command Processors 

A long running command is a command processor that allows other processing to 
continue after a command has begun processing, dsipush provides for continuation 
by the same or another processor under varying conditions. The caller of the ori- 
ginal command may run after that command returns. Other processing, for 
example messages, may occur between the calls to the various parts of the long 
running command processor. 

Long running commands run under an ost. nnt, ppt, and (limited) dst. They may be 
invoked directly by operator input, called by a command procedure, or called by 
another long running command. They return control to NetView after scheduling 
work but before processing is complete. NetView then processes other work that 
may be pending. Only long running commands are capable of acting like a 
NetView component, suspending for unrelated operator commands, including roll, 
and resuming, in turn. 

Long running command processors are often used to retrieve data from another 
task or from another domain without allowing the calling function or calling 
command procedure to proceed in the midst of this retrieval. During this retrieval, 
the processor's task may continue to receive messages and accept commands. 

For specific coding instructions, see "Writing a Long Running Command 
Processor" on page 64. 

Unattended and MVS Console Operator Task Command Considerations 

Command processors using dsipsstype=asypanel or other full-screen functions 
should test tvbautoo. If this bit is 1, full-screen mode is not permitted, tvbautoo 
indicates an unattended or mvs console operator task. 

Designing and Coding a Command Processor 

Command processors must adhere to the guidelines for user-written programming 
described in "General Coding Guidelines" on page 8. In addition, command 
processors must conform to the special requirements described in this section. 
After coding your command processor, follow the instructions under "Installing a 
Command Processor" on page 71. 

To allow for error recovery, consider testing theTVBRESET flag set by the reset 
command. You can code your command processor to examine this flag regularly 
and end itself prematurely if the flag is on. 
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Input 



Output 



When the command processor gains control, the registers contain the following 
information: 

Register Contents 

Undefined for command invocation. 

Storage address for long running command resume routines. 

1 The address of the command work block (cwb). The cwb contains 
the following: 

• A user save area (cwbsavea), which is the command 
processor's 72-byte save area 

• The address of the command buffer (cwbbuf) for a command 
call. This field is zero for a resume, abend reinstate, or logoff 
call. 

• The address of a service work block (swb) for calling service 
facilities (cwbswb) 

• The address of a parse descriptor block (cwbpdb) filled out if 
cwbbuf does not equal zero 

• A work area (cwbadatd), which is the command processor's 
256-byte temporary storage for keeping variables while 
remaining reentrant. 

13 The address of a standard 72-byte save area used to store the 
caller's registers. 

14 The return address. 

15 The entry address of the command processor. 
2-12 Unspecified. 

When a command results from the message automation table, tvbaiifr will contain 
the address of the message buffer structure that was automated. If tvbaiifr is zero, 
the command did not result from an automated message. (See Figure 8 on 
page 60 for an example of an automation internal function request buffer struc- 
ture). 



When NetView regains control, register 15 should contain a return code and the 
other registers should be restored to the caller's contents. 

Register Contents 

15 A return code 

0-14 Restored to caller's contents. 

If a regular command processor is called by a command procedure (NetView 
command list language, rexx, or high-level language), the return code is made 
available to the caller (&retcode, rc, hlbrc, respectively). NetView makes no other 
use of the return code. 

For an immediate command, NetView ignores the return code. 

For a long running command processor, the completion code is specified on the 
dsipop macro invocation. (See "DSIPOP - Remove Long Running Command" on 
page 190.) The register 15 return codes returned upon command resumption indi- 
cate processing options. (See "Message STIFLE" on page 67.) 
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Control Blocks 

Command processors usually access a command buffer and seven control blocks: 
cwb, pdb, swb, tvb, tib, mvt, and svl. In addition, type rd command processors 
running under a dst and type d command processors require the dsrb. Further, a 
command driven by means of message automation may require the automation ifr. 

Figure 7 on page 59 illustrates an example of the required control blocks and their 
relevant pointers. For detailed descriptions of these control blocks, see Chapter 7 
on page 119. 

The command buffers cwb, pdb, swb, dsrb, and aifr are specific to the command 
being executed. The tvb and tib are global to the task, and the mvt and svl are 
global to NetView. 
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Register 1 



CWB 



CWBBUF 



CWBPDB 



CWBSAVEA 



CWBTIB 



CWBSWB 



CWBADATD 



CWBDSRB 



SWB 



HDRMLENG = 24 
HDRBLENG = 104 
STET =HDRTYPET 
HDRD0MID='D0M1 
HDRTSTMP = X'1314150C 
HDRTDISP = 30 



24 30 



BUFHDR 



DSRB 



SWBTIB 



TIB 



TIBTVB 



Command Buffer 



-/ s- 



-4S- 



104 



ROUTE D2, LIST STATUS = OPS 



-f J- 



PDB 



PDBCMDA 



PDBBUFA 



PDBLENG 



PDBTYPE 



4S 
4 



PDBDISP 



30 
36 
39 
44 
51 



SCE 



•> ROUTE 



DSIRTP 



SCECADDR 



Displacement of entry 
in buffer 



~~ Type of delimiter 
Length of each element of command 



TVB 



MVT 



TVBMVT 



MVTSVL 



SVL 



NOTE: The NetView control block 
header (CBH) appears at the beginning 
of the CWB, DSRB, MVT, PDB, SVL, 
TIB, and TVB. 



Figure 7. Example of Control Blocks Used by Command Processors 
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BUFHDR 






Command 
Text 





IFRCODE 



IFRAUIND 
IFRAUACT 



IFRAUTBA 



IFRAUTBL 



IFRAUTA1 



IFRAUTA2 



BUFHDR 



MESSSAGE TEXT1 



BUFHDR 



MESSSAGE TEXT2 



* BUFHR 



MESSSAGE TEXT3 



Figure 8. Automation Internal Function Request. An example of a buffer structure when a command processor is 
driven from an automation statement in the message automation table. If tvbahfr=o, this command was 
not driven by an automation statement. 
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LA 


RO.PDBENTND-PDBENTRY 


AR 


R4,RQ 


CLI 


PDBLENG.0 


BE 




L 


R2.CWBBUF 


AH 


R2,PDBDISP 


SLR 


R1.R1 


IC 


Rl.PDBLENG 


appl 


i cation code to proces: 


CLC 


PDBN0ENT,=H'2* 


BNH 





Figure 9 shows sample code to access a command buffer. 



L R3.CWBPDB GET ADDRESS OF PDB 

r USING DSIPDB.R3 R3 IS BASE FOR PDB 

LA R4.PDBTABLE GET ADDRESS OF PDB TABLE 

USING PDBENTRY.R4 R4 IS BASE FOR A PDB ENTRY 

|< * Fi rst PDB entry i s for command name 

? CLC PDBNOENT,=H'l' ANY COMMAND PARAMETERS ENTERED? 
J BNH NO, GO HANDLE THIS SITUATION 

* Process 1st parameter after command name 

GET LENGTH OF PDB ENTRY 
BUMP PAST COMMAND NAME ENTRY 

WAS ONLY A DELIMITER SPECIFIED? 
YES, GO HANDLE THIS SITUATION 

GET ADDRESS OF COMMAND BUFFER 
POINT TO PARM IN BUFFER 
CLEAR LENGTH REGISTER 
GET LENGTH OF PARM 



MORE COMMAND PARAMETERS ENTERED? 
NO, GO HANDLE THIS SITUATION 



* Process 2nd parameter after command name 



GET LENGTH OF PDB ENTRY 
BUMP TO NEXT ENTRY 

WAS ONLY A DELIMITER SPECIFIED? 
YES, GO HANDLE THIS SITUATION 

GET ADDRESS OF COMMAND BUFFER 
POINT TO THIS PARM IN BUFFER 
CLEAR LENGTH REGISTER 
GET LENGTH OF PARM 



* Process nth parameter after command name 
etc. etc. 
Figure 9. Sample Code to Access a Command Buffer 



Writing a Full-Screen Command Processor 

This section describes how to write a full-screen command processor (fscp) which 
is a regular command processor that presents a full screen of data to an operator's 
terminal and runs only under an ost. For line-by-line presentation to an operator's 
terminal, see "Title-Line Output" on page 19. 

An fscp utilizes dsipsstype=asypanel to present data. In conjunction with long 
running command support, an fscp can be coded to allow additional ost work 
requests to be processed without ending the full-screen presentation. An fscp can 
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LA 


RO.PDBENTND-PDBENTRY 


AR 


R4.R0 


CLI 


PDBLENG.O 


BE 




L 


R2.CWBBUF 


AH 


R2.PDBDISP 


SLR 


R1.R1 


IC 


Rl.PDBLENG 


appl 


i cation code to proces; 



issue macro dsipss to request input and then perform other work before issuing 
macro dsipss type=psswait to receive the input. In addition, an fscp has direct 
access to operator input and can use macro dsiwat to synchronize an operator sce- 
nario. 

The issuer of the dsipss type=asypanel request can use dsipss type = psswait to wait 
on important NetView ecbs such as the termination ecb, the solicited poi ecb, the 
cross domain ecb, message ecbs, the reset ecb, and the user asypanel ecb. When 
control is returned from the psswait, it is usually better to check the NetView ecbs 
first for a post (your return code will be 56). If you expect the action of your input to 
be short (for example, quit), it is acceptable to check your own asypanel ecb first. 
The value of the post indicates the status of the dsipss type = asypanel request. The 
post codes can be found on page 201. 

Screen Formatting for the 3270 Data Stream 

Since the fscp is responsible for the 3270 data stream, the processor issues dsipss 
with type=scrsize to find the presentation space dimensions. If the result is larger 
than 24 by 80 characters, the processor may use the 3270 Erase/Write Alternate 
command. Otherwise, it must use the Erase/Write command. For more informa- 
tion on the 3270 data stream, refer to IBM 3270 Information Display System Data 
Stream Programmer's Reference. 

When dsipss with type=scrsize is issued for a terminal that uses 14-bit or 16-bit 
addressing and Query support (indicated in the logmode definition), the returned 
and actual screen size may be larger than the alternate screen size. If so, when 
the Erase/Write Alternate command is used to address the parts of the screen 
outside the alternate screen size, a terminal program check results. To avoid this 
problem, do either of the following: 

• Use a 24 by 80 character screen image data stream and use the Erase/Write 
command instead of the Erase/Write Alternate command. 

• Use a Write Structured Field command to create a partition structured field that 
controls the buffering in the terminal. For a more detailed explanation, see 
IBM 3270 Information Display System Data Stream Programmer's Reference. 

You will not normally need to send read instructions to the terminal. A read modi- 
fied is set up for you and executed whenever your operator uses an aid key. To 
receive the data, you must specify an input buffer and an input ecb on a dsipss 
type= asypanel request. When asking for input, be certain that you have unlocked 
the operator's keyboard (set bit 6 of wcc to '1'B). You may do this with the same 
dsipss invocation that requests the input or with an earlier one. You may also 
choose to reset the modified data tags. After requesting input, do not request input 
on a further dsipss type = asypanel request until your ecb is posted. 

Do not free the storage where your input buffer and ecb reside, until the ecb is 
posted. When necessary, you can force the ecb to be posted early by issuing 
dsipss type = cancel. Be aware that after you issue dsipss type = cancel, the oper- 
ator will not be able use his terminal until either another input request is made or a 
dsipss type = output restores the command facility screen. 

Reshow Option: Usually you will want to be able to suspend and resume full- 
screen processing by using macros dsifind, dsipop, and dsipush and by specifying a 
resume routine. This routine can present previously saved screen information. 

Logging Full-Screen Input/Output: NetView does not automatically log full-screen 
input and output. Use macro dsiwls to log pertinent data. 
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Escape Option: When you write a panel to the terminal, you must allow for oper- 
ator response by specifying an ecb address and Read buffer with at least one of 
your output requests. After you have done this, all input from the terminal will 
come to your program. 2 It is customary to respond to PF3 by terminating your fscp. 
If you want your fscp to make a temporary exit under other conditions, you must 
have previously prepared for resumption using dsipush. 

FSCP Functions: When an fscp sends a full screen of data to the display terminal, 
the system reads the 3270 data stream into the buffer area. At this point, the fscp 
can write more data to the screen while the operator is viewing or entering data. 
However, avoid writing over, or erasing, the operator's input area(s). 

When the data is read, NetView posts an event control block (ecb). Then the 
command processor processes the input and, optionally, presents more full-screen 
panels. While the fscp has a read outstanding, input to the terminal is treated as 
input to the command processor (not to NetView). 

When the command processor is called, it reads and writes to the terminal using 
dsipsstype=asypanel. The panel parameter of dsipss points to a 20-byte parameter 
list. See "DSIPSS - Presentation Services" on page 196 for details. 

dsipss with type=psswait allows the fscp to wait for both its own list of events and a 
list of events, such as important messages, for which the fscp may choose to inter- 
rupt its own processing. After waiting, the command processor tests the return 
code to determine if its ecb was posted or if a NetView ecb was posted. If the 
return code shows that a NetView event was completed, the command may return 
to NetView to allow the processing of the event to occur. If the panel ecb is posted, 
the fscp processes the input in the buffer. In this manner, the command processor 
has complete control of the screen format. The command processor returns to 
NetView after saving the screen status to enable future processing. The fscp can 
specify a resume routine (using dsipush) to enable the full-screen presentation to 
resume. 

dsipss with type=testwait allows the command processor to test whether a 
NetView event has already been posted. You can use this option before issuing 
dsipss type =asypanel to avoid performing input or output when NetView is already 
posted. This option allows early detection of interruptions. It also lets you return 
to NetView with a minimum of screen interruptions. 

You do not need to use type=psswait if you do not wish to allow "interruptions", 
such as messages and their resulting automation, or cross domain commands to 
process. The command processor can wait on its own list of ecbs. Even if you 
choose not to wait on other NetView events, you are strongly urged to include the 
ost termination ecb in the list. This ecb is located in the tvbtecb field of control 
block tvb. tvbtecb enables the command processor to be aware of any major con- 
dition requiring the command processor to clean up and exit. Use only the ecblist 
parameter with type = psswait in dsipss. 

dsipss with type = cancel allows you to change characteristics of the fscp. These 
characteristics include the input area length and the ecb address, type = cancel can 



2 NetView treats power off/power on and the attention signal as error conditions. For power off/power on, your ecb 
will be posted for a permanent error and your ost will be placed in termination status. The signal that results from 
the attention key causes NetView to set tvbreset. (Your psswait will also end). 
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be issued when a dsipss type = asypanel is active or inactive. It can also be issued 
if input from type= asypanel has been posted as complete or is not yet complete. 
This is sometimes necessary since there is no way to guarantee that the operator 
will enter data on any given panel. If an active asypanel input request is canceled, 
the system posts the ecb with a special post code. See page 201 for ecb post 
codes. The storage where the asypanel ecb is located must not be freed until a 
dsipss type = cancel is issued or the asypanel ecb has been posted by NetView for 
successful or unsuccessful input. 

Writing a Long Running Command Processor 

Long running command processors use macros dsipush, dsifind, and dsipop to syn- 
chronize the order in which functions are processed so that asynchronous events 
run in sequence or in parallel. Essentially, a long running command processor 
synchronizes functions so that programs it initiates complete before it ends and so 
that its callers do not resume until after it ends. 

dsipush identifies each of three routines that provide for command resumption, as 
well as recovery and termination. These routines are the resume routine, the abend 
reinstate routine, and the logoff routine, dsifind locates the storage you associ- 
ated with the dsipush input name, dsipop indicates that a long running command 
has completed. 

When one of these routines receives control, cwbbuf is set to zero and register 
contains the storage pointer associated with the long running command (0 if no 
storage). Additionally one of the following is set: 

• For a resume routine, the tvbresum bit is set on. 

• For an abend reinstate routine, the tvbabend bit is set on. 

• For a logoff routine, the tvblogof bit is set on. 

Note: The flags tvbresum, tvbabend, and tvblogof are meaningful only when your 
input cwbbuf address is zero. 

The other registers contain the information described under "Input" on page 57. 

When a resume, abend reinstate, or logoff routine returns control to NetView, all 
registers must be restored. You must set register 15 to tell NetView what action to 
take, as described in the following sections. 



RESUME Routines 



Before invoking any subordinate command processors or command lists, and 
before issuing dsipss type = pssw ait (or testwait), the long running command (lrc) 
processor should schedule a resume routine (using dsipush). The resume routine 
suspends any other active long running command processors and enables the long 
running command processor to regain control. 

The first request at the top of the long running command chain defines the control- 
ling resume routine. If you use dsipush while another resume routine is in control, 
the new resume routine becomes the controlling routine. All other resume routines 
are temporarily suspended. The period of suspension is dependent on the environ- 
ment from which the lrc received control. If the lrc was called due to an asyn- 
chronous event, such as an operator command or the automation of a message, 
then the NetView roll command (if issued) could move (rotate) the lrc to the 
bottom of the long running command chain, thereby giving control to the next lrc. 
If the lrc received control by direct call from another lrc (including direct com- 
mands from NetView command list language, rexx, and high-level language 
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command procedures), then the two commands are regarded as being related by 
that direct call. The roll command (if issued) acts against both (or all) such 
related commands as a group, moving them all together and preserving their 
order. In either case, dsipop can remove the topmost resume routine, giving control 
to the next long running command. 

Note: Neither the roll command nor dsipop cause an asychronous interrupt. A 
command gives up control only by returning to its caller, except for the action of 
immediate commands. 

dsipop can also be used to remove (by name) a resume routine that is not at the top 
of the stack of the long running command chain (not in control) when you are 
resumed. This action is regarded as a cancelation of that lrc unless your dsipop 
invocation specifies compcde. If the lrc that was removed was part of a larger 
group, the calling lrc will be given control as soon as the current process allows 
and will be given a cancel indication, as follows: 

• NetView command list language command lists are stopped 

• rexx command lists receive a halt 

• all others receive a -5 completion code. 

See NetView Customization: Using PU1 and C for more information on cancelable 
and non-cancelable high-level language procedures. 

All command procedures are long running commands. A command procudure's 
resume routine blocks resume routines pushed earlier exactly like other long 
running command processors. A pause or wait state for a command procedure is 
no exception. 

dsipush for a resume routine is either major or minor. A major dsipush places the 
new resume routine at the top of the long running command processor stack sus- 
pending previously-issued long running commands from executing. A minor 
dsipush places the new resume routine on the stack after any leading command 
procedures (in the same group), and thus allows the leading command procedures 
to complete before the new resume routine gains control. Command procedures 
already suspended by other long running command processors are not affected. 

A major dsipush would be used to suspend a command procedure's execution until 
your long running command processor executes a dsipop. A minor dsipush is used 
to allow a calling command procedure to complete after which your resume routine 
gains control. 

Completion Codes An lrc may return a completion code to the lrc that invoked it 
(in the same group) by specifing a value for the compcde keyword on the dsipop 
macro. If an lrc was invoked asynchronously, the value specified for compcde is 
ignored. The completion code is passed to the calling lrc in cwbrcode, upon 
resumption. 

Return Codes A resume routine may return control to its caller many times before it 
completes, to allow messages, queued commands, called lrc's, and other 
asychronous work to process. Upon the initial return (when commanded, 
cwbbuf-1 =0), the value in register 15 is ignored. After each resumption, the value 
in register 15 conveys the lrc requirments for stifle (For an explanation of stifle 
see "Message STIFLE" on page 67). Register 15 = -8 requests stifle; register 15 
= +8 requests no stifle. Meanings for other return codes are reserved. (For com- 
patibility with prior releases, a zero return code is allowed after dsipop is issued to 
remove the lrc from the stack.) 
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An important part of any resume routine's function is screen control. Since the 
state of the operator's terminal is not known (see "Screen Identifier" on page 69) 
on entry, the resume routine must ensure the operator is not locked out by a panel 
left over from a previous long running command processor. This may mean 
issuing a message (dsipss type = flash) that guarantees that the command facility 
panel and command line are available to the operator. It might also mean dis- 
playing a full-screen panel (dsipss type =asypanel). 

Note: The screen control requirement means that the NetView-supplied routine 
dsilrcr8 should not be used as a resume routine with NetView as was sometimes 
appropriate with nccf. dsilrcrs can be used as an abend reinstate or logoff 
routine if no clean up besides the dsipop is needed. 

Caution: Care should be taken when using messages for screen control. Issuing a 
message on every resumption is excessive and can cause looping if the message 
is automated or routed. Use the screen serial number (tibscrsn) to determine 
when to issue messages upon resumption. Be especially cautious when issuing 
messages upon resumptions under the ppt task, since all messages are routed and 
may generate new activity (timer requests, for example) under the ppt.: To assist 
resume routines that display panels, NetView provides status information via 
tibscrid (see page 69). To assist resume routines that do not display panels, 
NetView provides a flag, tiblrcnp (long running command new promotion), that is 
set after any resume routine is removed from the top of the stack (whether via 
dsipop or by use of the roll command). By examining this bit, the resume routine 
can determine whether any other long running command processor has executed 
since it last had control. For example: iftiblrcnp='1'b.then exercise screen 
control, else continue. 

A completed resume routine (one that has issued dsipop against itself) need not be 
concerned with screen control since the following resume routine will assume 
responsibility. Ending messages (which were recommended with nccf) issued 
when a long running command processor finished are not appropriate in NetView. 

NetView attempts to give the operator an opportunity to recover from operator 
errors or certain program errors through the use of the attention signal or reset 
(normal) command. When attention is signalled or the reset command executes, a 
flag, tvbreset is set. Additionally, an ecb, tvbreste, is posted. It is recommended 
that all commands, and especially long running command processors, test 
tvbreset regularly. Whenever it is set, the command should terminate its proc- 
essing (dsipop if appropriate) and return to NetView. 

The following scenario illustrates the use of dsipush and dsipop: 

1. A command list invokes a command, and to complete the request the 
command processor must request data from a dst. 

2. The command processor issues dsipush specifying a resume routine. At this 
point the command processor has become an lrc (long running command). 

3. The command processor uses dsimqs to queue a buffer with ifrcode set to 
ifrcodcr containing its request for data to the dst. 

4. The command processor returns to its caller. The terminal has been left in 
whatever state it was in when the command list was running. In this case, we 
will assume the command facility screen is displayed. 

5. This operator's task is idle (the command list is suspended by the dsipush); 
therefore, the resume routine defined earlier by dsipush is immediately called. 
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Message STIFLE 



6. The command processor finds cwbbuf = (no command is being passed) and 
tvbresum is set, but tiblrcnp is not set. The command processor returns 
control to its caller. 

7. A message is received and displayed. The command processor is called again 
as a resume routine as in the previous step. 

8. The operator issues a full-screen command, which issues its own dsipush and 
waits for input. 

9. The operator exits (or rolls away from) this latter command processor. 

10. The panel of the second command processor is left in place, and the original 
command processor's resume routine is called. This time tiblrcnp is set. The 
command processor issues a flash message: "still waiting for data." The 
command facility screen is restored by dsipss. 

11. An ifrcodcr buffer containing the dst reply is received. After issuing dsifind, 
the ifrcodcr command processor places data into the long running command 
processor's lrc storage (as defined in the original dsipush). The ifrcodcr 
command processor only saves the data since another lrc may have been in 
control at this point. 

12. The command processor is resumed again. Finding its data request satisfied, 
it completes its function and issues dsipop against itself, using the compcde 
keyword on dsipop to indicate the nature of the completion. The command 
processor returns a return code of 8 in register 15. 

Note: For compatibility with prior releases, a zero return code is allowed after 
dsipop is issued to remove the lrc from the stack. 

13. NetView calls the next resume routine, the command list invoking the original 
command, which then continues. 

14. The command list receives the return code (&retcode) that was specified for 
compcde on the dsipop. 

In some cases a resume routine may wish to return control to NetView without 
giving up control of the operator's display. For example, the screen might be 
dynamically updated based on information sent by another task in the form of an 
ifrcodcr message. (See "IFR — Internal Function Request" on page 133.) To 
assist with such a function, NetView provides two tools: message stifle and a 
screen identifier. 



A resume routine can request a message stifle when it returns control to NetView. 
This means that ordinary line mode messages will not be displayed and the 
operator's screen is not disturbed by the processing of the messages. 

Some messages are displayed by NetView whether or not stifle is in effect. These 
messages are said to break stifle mode. The following messages can break the 
stifle mode: 

1. Action messages with iSTnnnA or DsmnnA identifiers 

2. Messages which request a reply (hdrtypey, except the assign = copy of 
hdrtypey, which does not break stifle) 

3. Any message issued with dsipss type = flash (the intended use of dsipss 
type= flash is for command echoes and screen control messages). 

If stifle is broken, it remains off until reinvoked by a resume routine. 

Chapter 4. Writing Command Processors in Assembler Language 67 



ROLL Function 



A request for stifle can be honored only while the NetView log or the hardcopy log 
remains active. NetView counts messages that are stifled and displays message 
DS15931 to remind the operator that he needs to consult the NetView log or hardcopy 
log to see these messages. A request for stifle will not be honored while the 
command facility screen is in place. It is assumed that the long running command 
processor will gain control of the screen through the use of dsipsstype=asypanel 
before requesting stifle. 

stifle affects only line mode messages. A full-screen display is not affected. If, for 
example, the result of a start domain command (the logon panel) is delayed long 
enough for a long running command processor to gain control, the returning logon 
panel will be displayed without regard to the stifle. 



A roll group is NetView's way of allowing the operator to switch from one function, 
such as hardware monitor, to another function, such as session monitor, and return 
to the place at which the operator left the function the last time. This is similar to 
window processing in other applications. 

A roll group is a set of related dsipush macro requests, dsipush begins a new roll 
group when it is invoked from an asynchronous command environment. Operator 
commands, commands generated by automation, and commands scheduled via 
dsimqs are asynchronous. A command called directly from another lrc is synchro- 
nous. The synchronous lrc is added to the roll group started by the asynchronous 
lrc and blocks it until a dsipop is issued against the synchronous lrc. The current 
roll group is defined as the roll group that is currently first on the long running 
command chain. 

The roll command treats each specified roll group as a unit when manipulating 
the chain. The roll command takes the topmost roll group and moves it to the 
bottom of the stack. All elements within the roll group maintain their position 
within the group. 

Roll Group Usage: The simplest roll group would be a command that invoked 
dsipush with a resume routine. The resume routine allows the command processor 
to respond to a roll request. If this command accepted command input from the 
operator (via dsipsstype=asypanel), a roll command would cause the lrc to move 
(rotate) to the bottom of the long running command chain. Eventually, when 
another lrc has been similarly rotated to the bottom of the long running command 
stack by the roll command (or ended with dsipop) the resume routine would regain 
control. 

You can use multiple dsipush requests (with different resume routines or merely 
different storage pointers) to implement things such as a hierarchical panel struc- 
ture. In this situation, rolling away and then back brings the operator back to the 
same panel last presented, and ending a panel (the operator uses PF3, and the 
program invokes dsipop) redisplays the panel 'above' the current one. 

The following scenario describes how a full-screen function would make use of the 
roll capability. 

• Issue dsipush for a resume routine. 

• Provide a line on your panels for NetView command input, using 3270 data 
stream orders. 
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Screen Identifier 



• When the operator enters data on the command line, the input data stream will 
contain orders that identify the area of the screen into which the operator 
typed. 

• When command entry is detected (use dsices to verify command), build a 
standard NetView buffer with hdrmtype=hdrtypet and issue the dsimqs macro 
to send the buffer to the operator's (own) task, using tvbopid as the destination 
of the DSIMQS. 

Note: You must translate the command input to upper case if the language the 
operator is using has upper and lower case characters. 

• Return to NetView to allow the command to be processed. 

• NetView will reinvoke your resume routine when the command has completed 
processing and when your resume routine is the first routine on the stack (and 
is, therefore, the current roll group). 

If the command entered was roll, the roll command processor will automat- 
ically switch your roll group to last. 

If the command entered establishes a new roll group, your roll group is 
pushed down on the stack and the new group becomes current. When the 
operator exits from the new roll group, your roll group is invoked by NetView 
calling the topmost resume routine. 

• You should also detect PF6 and PF18 as roll. In this case you would build the 
command buffer, but you must look up the command name for the dsiroll load 
module using dsices and then issue dsimqs to queue the buffer as described 
above. 

• In order to allow the operator to switch to your function from a different roll 
group directly without roll, you must define a command (which could be your 
function's command name with no operands provided) as a re-show request. 

When your command processor is entered (and there are no operands) with 
the re-show requested, you would issue dsipush with promote = yes to move 
your roll group to the head of the stack. You would then proceed by 
refreshing the screen from the last panel the operator saw. 

Note: dsipush with promote = yes exchanges the storage address in the dsipush 
parameter list with the one already associated with the named request, and 
returns the old value in register 0. Therefore, you may issue dsifind to deter- 
mine the current address and specify it on the promote=yes request to make 
sure the address stays the same. If you do not specify the address, the zero 
value in the parameter list will replace the current value. 



Requesting stifle is not a guarantee that a long running command processor's 
panel will not be modified; therefore, a means is provided to determine whether 
such modifications have occurred. After writing the panel to the screen, a long 
running command processor should save the value of tibscrid. Upon regaining 
control, a resume routine can compare the present and saved values of tibscrid to 
determine whether and to some extent, what type of screen modifications have 
occurred since it last had control. 

tibscrid, a four-byte field, consists of two subfields: 

tibscrsn The low order three bytes, which form a serial number for the 

screen's contents. This number is incremented whenever anything 
is sent to the screen that changes what the operator sees. 
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tibscrm The high order byte which is a state change indicator. A change in 

tibscrm usually means a dsipsstype= cancel has been issued. It 
may also mean that a lock keyboard or other non-data 3270 
command has been sent to the terminal. 

When a long running command processor regains control and tibscrid is 
unchanged, it may resume processing as if it had never lost control. 

When tibscrm (and not tibscrsn) has been changed, the long running command 
processor should reestablish its read by issuing dsipsstype=asypanel to send a 
write/unlock (XT182') to the terminal and respecify the ecb, if any, by which the 
long running command waits for input. This will avoid the necessity to refresh the 
screen. 

When tibscrsn has changed, some visible modification to the long running 
command processor's panel has been made. It will be necessary to rewrite the 
entire panel. 

ABEND Reinstate Routines 

An abend reinstate routine performs a required recovery action, such as freeing 
control blocks, after NetView recovers from a task's abnormal ending (abend), 
abend routines cannot be used while running under the dst since dst tasks are not 
reinstated after abnormal endings. While running under the dst, use a logoff 
routine instead. 

The abend routine assesses the damage caused by an abnormal end and either 
keeps or cancels the long running command. (There must be an abend reinstate 
routine for each command in the stack.) With its return codes in register 15, the 
abend routine notifies the task whether the command is to be kept or removed from 
the queue and freed. 

Return Code Meaning 

Keep the long running command request queued. 

8 Remove the currently queued long running command request from 

the queue. 

If the routine keeps a long running command, the resume routine runs the first time 
the task has no other work to perform. All stacked long running command routines 
are maintained in their current order, abend reinstate routines cannot issue dsipop 
or DSIPUSH. 

Once a task recovers from an abnormal ending, all abend reinstate routines are 
called, starting with the top one in the stack, which is the most recent. When the 
abend reinstate routine returns to its task, it specifies whether the associated 
command is to be left on the stack or removed from the stack. 



LOGOFF Routines 



A logoff routine gives the command processor control before the task ends. The 
task is not reinstated, and the command processor can perform any final clean-up 
processing, such as closing a data set or freeing storage. (There must be a logoff 
routine for each command in the stack.) 

A logoff routine is called sequentially for each request on the queue, logoff rou- 
tines cannot issue dsipop or dsipush. 
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When the command processor returns to the task, requests are taken off the queue 
and freed. 

NetView ignores all return codes for logoff routines. 

When a task ends, all the logoff routines are called starting with the top, or most 
recent, request on the stack. Each request is removed from the queue and freed. 



Automation Task Command Processors 



Commands written to run under ost tasks must consider the effects of running 
under automation tasks and mvs console tasks. These osts have the tvbautoo bit 
set to 1. This indicates that immediate commands and full screen mode commands 
are not supported in this task. 



Installing a Command Processor 



To install a command processor, define the command verbs with cmdmdl state- 
ments as described in the NetView Installation and Administration Guide. If your 
command processor will do line mode output (dsipss type = output), you should 
specify echo=y. If your command processor does full screen mode output (dsipss 
type = asypanel), you should specify echo=n. Then assemble and link-edit the 
command processor into a load module in the NetView load library. NetView loads 
and calls the command processor according to its linkage editor attributes. 

See "Preparing Your Code for Use" on page 4 for information on testing your 
command processor before use. 



Template for a Command Processor 



The following template illustrates basic entry and exit processing required by all 
command processors. It is available on-line in the NetView sample library 
(Syslcnmsamp) under the name CNMS4202. 
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ATMPCMDP CSECT 
*********************************************************************** 

* * 

* (C) COPYRIGHT IBM CORP. 1989 * 

* * 

* IEBCOPY SELECT MEMBER* ( ( CNMS4202, ATMPCMDP, R)) * 

* * 

* MODULE NAME: * 

* * 

* FUNCTION: * 



SYNTAX: 



INSTALLATION: 



INPUT: REG 1 - ADDRESS OF COMMAND WORK BLOCK (DSICWB) 

REG13 - ADDRESS OF CALLER'S SAVE AREA 

REG14 - RETURN ADDRESS 

REG15 - ENTRY ADDRESS 

OUTPUT: 



REGISTERS: 

REG - REG14 - RESTORED UPON RETURN 

REG 15 RETURN CODES: 

- SUCCESSFUL 



* NETVIEW MACROS: * 

* * 

* DSICBS - CONTROL BLOCK SERVICE * 

* * 

************************************************************** 
Figure 10 (Part 1 of 4). Template for a Command Processor 
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EJECT 

DSICBS DSICWB,DSIMVT,DSIPDB,DSISVL,DSISWB,DSITIB,DSITVB, 
PRINT=NO 



RO 


EQU 





Rl 


EQU 


1 


R2 


EQU 


2 


R3 


EQU 


3 


R4 


EQU 


4 


R5 


EQU 


5 


R6 


EQU 


6 


R7 


EQU 


7 


R8 


EQU 


8 


R9 


EQU 


9 


RIO 


EQU 


10 


Rll 


EQU 


11 


R12 


EQU 


12 


R13 


EQU 


13 


R14 


EQU 


14 



MVT 

TVB 

TIB 

CWB 

BASE REG 

SAVEAREA 

R15 EQU 15 

EJECT 
***************************************************************** 

* * 

* SAVE REGISTERS AND ESTABLISH BASE REGISTER * 

* * 

*********************************************************************** 



PROLOG 



USING ATMPCMDP.R12 
Figure 10 (Part 2 of 4). Template for a Command Processor 



USING *,R15 




B PROLOG 




DC C'ATMPCMDP &SYSDATE. 


AT &SYSTIME. ' 


DS OH 




STM R14,R12,R12(R13) 


SAVE REGISTERS 


DROP R15 




LR R12.R15 


SET BASE REGIS' 
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LR 


R11.R1 


USING 0SICWB.R11 


LA 


Rl, CWBSAVEA 


ST 


R1,8(R13) 


ST 


R13,4(R1) 


LR 


R13.RI 



******************************************** *************************** 

* * 

* ESTABLISH ADDRESSABILITY TO THE COMMAND WORK BLOCK (CWB) AND SET * 

* UP THE SAVE AREA USING CWBSAVEA * 

* * 

*********************************************************************** 

LOAD CWB ADDR 

Rll BASE FOR COMMAND WORK BLOCK 
USE CWBSAVEA FOR SAVEAREA 
STORE MY SA INTO CALLERS SA 
STORE CALLERS SA IN MINE 

R13 HAS MY SAVEAREA ADDRESS 

*********************************************************************** 

* * 

* ESTABLISH ADDRESSABILITY TO THE TASK INFORMATION BLOCK (TIB), THE * 

* TASK VECTOR BLOCK (TVB) , AND THE MAIN VECTOR BLOCK (MVT) . * 

* * 
*********************************************************************** 

L R10.CWBTIB GET DSITIB ADDRESS 

USING DSITIB, RIO ESTABLISH ADDRESSABILITY 

L R9.TIBTVB GET DSITVB ADDRESS 

USING DSITVB, R9 ESTABLISH ADDRESSABILITY 

L R8.TVBMVT GET DSIMVT ADDRESS 

USING DSIMVT.R8 ESTABLISH ADDRESSABILITY 

* 

XC CWBADATD.CWBADATD ZERO AUTODATA AREA 

SLR R15.R15 ZERO RETURN CODE REGISTER 

*********************************************************************** 



MAIN PROCESSING GOES HERE 



*********************************************************************** 
Figure 10 (Part 3 of 4). Template for a Command Processor 
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*********************************************************************** 



EXIT 



*********************************************************************** 



RETURN 


EQU * 






L R13,4(R13) 


GET CALLERS SAVEAREA ADDRESS 




L R14,12(R13) 


RESTORE REG14 




LM R0.R12,2G(R13) 


RESTORE REGS 




BR R14 


RETURN 




SPACE 






EJECT 






LTORG 




* 


EJECT 




DSICWB 


DSECT 






ORG CWBADATD 


AUTODATA AREA 




DS XL(256-(*-CWBADATD)) 


AUTODATA LENGTH CHECK 




END 





Figure 10 (Part 4 of 4). Template for a Command Processor 
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Chapter 5. Writing User Subtasks 



Types of User Subtasks 



NetView provides two methods for writing user subtasks. The first and recom- 
mended method uses the data services task (dst) interface as a coding base. The 
dst base provides interfaces for the following functions: 

• An initialization user exit 

• A subtask processing module (dsizdst) 

• cnmi service 

• vsam service 

• Data Services Command Processor (dscp) 

The dst provides an ideal structure for user-written tasks since the dst can be 
defined with vsam services, cnm services, or neither service (user-defined functions 
can be implemented within the data services command processors). The dst pro- 
vides all the low-level user subtask functions that you would otherwise have to 
code if you wrote a complete optional substask. An optional subtask should only 
be written if access to the subtask ecb processing loop is required. 

The other method requires that you code an optional (opt) subtask. With this 
method, NetView supplies an intertask communication (message queue) ecb and a 
termination ecb. It is up to you to provide an appropriate ecb processing loop and 
any additional function. This requires more coding effort than the second method, 
but it allows for more flexibility as to what kinds of functions can be implemented. 



Optional Subtask Processing 
Overview 



A user subtask requires the following processes: 

• Installation 

• Initialization 

• Processing 

• Termination 

Installation The task statement is required to define an optional subtask to 

NetView. It is added to the dsidmn memeber of dsiparm. The dsidmn 
member is processed during NetView initialization. 

Initialization The initialization process of the subtask performs any required initial- 
ization functions. Examples would be acquiring NetView control blocks 
via the dsilcs macro and acquiring dynamic storage via the dsiget 
macro. 

Processing The processing part of a subtask should begin by invoking the dsiwat 

macro to wait on an ecb list. The ecb list must include the subtask termi- 
nation ecb (tvbtecb) and generally includes the message queue ecb 
(tvbmecb), used for intertask communication (via the dsimqs macro). 
User defined ecbs can also be included in the ecb list. 
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Termination The termination process must free all acquired resources (storage, 
NetView control blocks, etc.) and return to NetView. 



Message 



f Enter Subtask J 




Initialization 



Issue DSIWAT 
Macro on the 
ECB List 



YES 




Process the Data 



User-Defined 
Processing 



Release 
Resources 



■+T EXIT J 



Termination 



Set 
TVBTERM = 1 



Figure 11. Subtask Organization 
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Installation 



A task statement for the subtask must be coded in the dsidmn member of the 
dsiparm data set. 

The task statement defines the task to NetView and provides the following 
information: 

• mod keyword - the name of the module to be run as a subtask. The module 
must be link-edited into the proper NetView library. 

• tskid keyword - The task name. Each task in NetView must have a unique task 
name. 

• mem keyword - Specifies the user-defined initialization member found in 
dsiparm to be used by this task. The user is responsible for the format and 
contents of the specified member. The member can be read and processed 
during the task initialization. 

• pri keyword - Specifies the relative task priority (1-9). 1 is the highest task pri- 
ority that can be assigned, and 9 is the lowest. 

• init keyword - Specifies whether the task is to be started during NetView initial- 
ization (init=y) or via the start command only (init=n). 



TASK M0D=USERM0D,TSKID=USERTASK,MEM=USERMEM,PRI=7,INIT=Y 



In the example above, the subtask identification is usertask. usermem is the name 
of the dsiparm member (for mvs) or the file with file type nccflst (for vm) that con- 
tains additional initialization information. The priority of the subtask is 7, and the 
subtask will be started during NetView initialization. For more information on the 
task statement, see the NetView Administration Reference. 



Initialization 

Attaching the Subtask 

Issuing the start task command or specifying init=y on the task definition state- 
ment causes a normal attach. The tvbterm bit in the tvb is set to off (0). 

When an opt subtask is attached, the registers contain the following information: 



Register 

1 
13 

14 
15 
0,2-12 



Contents 

The address of the task vector block (tvb) 

The address of a standard 72-byte save area used to store the 
caller's registers 

The return address 

The entry address of the subtask 

Unspecified. 



The control blocks used in attaching an opt subtask are tvb, tib, mvt, and svl. The 
tvb contains the address of the tib and the mvt, as well as the task control block of 
the operating system. The mvt contains the address of the svl. Refer to Chapter 7 
on page 119 for detailed descriptions of these control blocks. 
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TVBMEMNM Field 



After the subtask is initialized and before it starts processing, it must indicate that 
it is ready to begin processing by doing the following: 

• Setting the tvbopid field of the tvb to a unique subtask identifier 

• Setting the tvbactv bit to on. 

One method of setting the tvbopid field is to copy the contents of tvblunam into 
tvbopid. (tvblunam is the value of the tskid parameter in the task definition state- 
ment.) Another method is to use a predefined value. 



The value of the mem keyword of the task definition statement is generally used as 
the name (one to eight characters) of an initialization member or file. The value of 
the mem keyword is found in theTVBMEMNM field of the tvb if initialization input is 
required. If the subtask is coded to process this member or file, the following 
macros would be invoked to read from the member or file: 

• dsidks type=conn,name=dsiparm to connect the subtask to disk services for the 
dsiparm dataset. (For vm, you would use name=nccflst.) 

• dsidks type =find,name= tvbmemnm to find the member or file and read the first 
record. 

• dsidks type = read to read a record. The read would be repeated until a user- 
defined end statement is read or until an end-of-file return code is returned. 

• dsidks type = disc to disconnect from disk services. 

If the initialization member or filename is not used by the subtask, you can use 
tvbmemnm for other purposes, depending on the manner in which the mem keyword 
of the task statement is specified. For example, you may decide to use this field as 
the dd name to be opened by the subtask; or you can specify a default operator to 
receive messages. 

Processing 

ECB Loop 

The processing section of a subtask usually begins by issuing the dsiwat macro to 
wait on an event control block (ecb) list. The ecb list must contain the subtask ter- 
mination ecb (tvbtecb), and generally contains the message queue ecb (tvbmecb), 
used for intertask communication via the dsimqs (Message Queuing Service) 
macro. In addition to these two NetView provided ecbs, the ecb list can also 
contain user defined ecbs for additional functions. 

Intertask Communication 

If your task will receive messages or commands from other tasks (or exits), include 
the (normal) message ecb (tvbmecb) in your task's wait list. Optionally, you may 
wish to include also the high and low priority message ecbs (tvbmecbh and 
tvbmecbl). If the the task services the high and low queues, you should set the bit 
tvbmm to '1'B to indicate this. (When tvbmm is 'O'B, the message queuing service 
will put all messages on the normal queue, regardless of how they were sent.) You 
should retest the high priority ecb after each item of work on a lower queue, to 
allow higher priority work to preempt the queue of lower priority work. 

Each message queue should be thought of as a triplet: a private queue, a public 
queue, and an ecb. (There are two queues for reentrancy reasons.) 
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Table 3. 


Message Processing Triplets. 






Priority 


Private Queue 


Public Queue 


ECB 


High 


TVBMPRQH 


TVBMPUBH 


TVBMECBH 


Normal 


TVBMPRIQ 


TVBMPUBQ 


TVBMECB 



Low 



TVBMPRQL 



TVBMPUBL 



TVBMECBL 



Message Queue Processing: When a message buffer is received by your subtask, 
the TVBMECB event control block will be posted and the message buffer will be 
inserted at the head of the public message queue pointed to by tvbmpubq (this is a 
lifo queue). When your subtask detects that the tvbmecb ecb has been posted, the 
public message queue can be moved to the private message queue (tvbmpriq) for 
processing. Because the dsimqs service handles situations such as main line inter- 
ruption (i.e., an exit running asynchronously queues a message buffer to your 
subtask), simultaneous processing in multiple subtasks, and parallel processing in 
multiprocessor environments, the assembler compare and swap (cs) instruction 
must be used to acquire message buffers from the public message queue. 

To process the public message queue, do the following: 

1. Set tvbmecb to 0. 

2. Use the assembler cs instruction to obtain the queue of buffers from tvbmpubq 
and store zero into tvbmpubq. 

3. Reverse the order of the queue (make it fifo) so that the message buffers can 
be processed in the order that they were actually received. 

The following segment of assembler code demonstrates how to move the public 
message queue to the private message queue (addressability to the dsitvb control 
block is assumed): 



MESSAGED 


! EQU 


* 




XC 


TVBMECB .TVBMECB 


CHEKQ 


EQU 


* 




SLR 


RO.R0 




L 


R3, TVBMPUBQ 




CS 


R3.R0, TVBMPUBQ 




BNE 


CHEKQ 




USING 


BUFHDR.R3 


REVQ 


EQU 


* 




L 


R1.H0RNEXTM 




ST 


RO.HDRNEXTM 




,LR 


R0.R3 




LTR 


R3.R1 




BNZ 


REVQ 




ST 


R0, TVBMPRIQ 


PROCESS 


EQU 


* 



BRANCH HERE WHEN TVBMECB POSTED 
CLEAR MESSAGE ECB 

CLEAR SWAP REGISTER 
LOAD COMPARAND REGISTER 
CS ZERO ON THE PUBLIC QUEUE 
RETRY IF TVBMPUBQ MODIFIED 
MAP BUFHDR ONTO QUEUE HEAD 
MAKE LIFO QUEUE A FIFO QUEUE 
Rl = POINTER TO NEXT BUFFER 
SET NEXT TO PREVIOUS 
MAKE CURRENT PREVIOUS 
END OF QUEUE? 

CONTINUE UNTIL END REACHED 
ANCHOR THE PRIVATE QUEUE 
BEGIN BUFFER PROCESSING 



The message buffers can be dequeued from the private message queue and proc- 
essed. After each buffer is processed, it must be freed. Message buffers were 
obtained with dsiget q=no and subpool o so they must be freed with dsifre q = no 
and subpool o (these are the default values). 
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Message Buffer Contents: Message buffers are discussed in detail in Chapter 2 
on page 7. They may be actual messages to be displayed (hdrmtype = hdrtypeu) 
or internal function requests (hdrmtype = hdrtypei). For internal function requests 
queued to your optional subtask, you can define your own function type by setting 
the ifrcode field to ifrcodus (user function) and then taking appropriate user- 
defined action when the buffer is received by your optional subtask. 

Using IFRCODUS to Invoke a User-Defined Command Processor: The following 
technique should be used to call a user-defined command processor under your 
optional subtask: 

1. Issue dsimqs (from any subtask environment) to send an internal funtion 
request (hdrmtype = hdrtypei and ifrcode = ifrcodus) to your optional subtask. 
The command name and command parameters should follow the dsiifr portion 
of the buffer passed to dsimqs. 

2. When processing the ifrcodus message buffer under your subtask, add 2 to 
hdrtdisp to adjust the displacement to the start of the command and subtract 2 
from hdrmleng to keep the length consistent. 

3. Follow the steps documented under "Calling a Command Directly" on page 21 
to call the command processor. 

The command processor called should only be defined as type = d or type=rd on its 
respective cmdmdl statement in dsicmd, and must be a user-written command 
processor. Do not call any NetView-provided command procedures from your 
optional subtask. 

Note: The dsizcsms and dsizvsms macros cannot be used under your optional task. 

Sending Message Buffers: Use the dsimqs macro to send message buffers to other 
subtasks. These message buffers may contain actual operator messages to be dis- 
played, or they may contain internal function requests (ifrs) to be executed by the 
receiving subtasks. See Chapter 8 on page 161 for details of the dsimqs service. 

Operator Communications 

Sending Messages to Operators You may use dsipss type - output or type=immed to 
send messages. Messages sent this way will go to the operator who started the 
task (owner). If the task was started during NetView initialization or the owner has 
logged off, the message is sent to the ppt for routing and automation.: The dsimqs 
macro can also be used to send messages to the authorized receiver of messages 
or to the operator that started the subtask. The tibmsgnm field of the dsitib control 
block will contain zeroes if the task was started during NetView initialization 
(init=y was specified on the task definition statement). 

Note: Commands from operators are buffers with hdrmtype equal to hdrtypet, 
hdrtypeb, or hdrtypqc. All other commands are hdrtypei. 

Logging Messages: You can use macro dsiwls to write messages from the 
subtask to the network log, the mvs system log, an external log, or a NetView 
sequential log. See "DSIWLS - Write Log Services" on page 214 for more infor- 
mation. Hard-copy logging may not be started for user-written subtasks. 
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Termination 



Calling Command Processors See "Calling a Command Directly" on page 21. 

Notes: 

1. Command lists, immediate commands, and regular commands cannot be 
called from an optional task, only command processors defined as type=d or 

TYPE = RD. 

2. dst service macros dsizvsms and dsizcsms cannot be invoked under an optional 
task. 

User-defined Functions: When a user-defined ecb is posted for work, a user- 
defined command processor can be called as explained in the previous section or 
a subroutine can be called to perform the requested function. It is up to you to 
decide how you want to handle your implemented function. 



Terminating the OPT: When a subtask terminates normally, the tvbterm bit is set 
to on, indicating that the subtask's resources should be released. When a subtask 
terminates abnormally, the tvbterm bit is set to on and the subtask is reattached. 
(This is called a cleanup attach.) When the subtask regains control, it frees the 
resources it had obtained and exits normally. 

Include the tvbtecb field of tvb in the subtask ecb list for each opt subtask you 
write. When a close normal command is issued and all operators have logged off, 
the main task posts the tvbtecb of the subtask. This posting indicates that subtask 
termination is requested. When the subtask finds the tvbtecb posted, the subtask 
must perform the following: 

• Release all resources (See Releasing Queued Storage below.) 

• Set the TVBOPiD field to blanks 

• Set the tvbactv bit to off 

• Set the tvbterm bit to on 

• Reload the registers originally passed and return to NetView. 

After releasing all resources, no NetView macros may be issued. 

Releasing Queued Storage: The dsigetq=yes option enables storage to be easily 
freed for both normal and abnormal subtask termination. During a subtask termi- 
nation, use dsifre aq= yes to free any remaining storage obtained by dsigetq=yes. 

To release all queued storage, issue dsifre aq = yes. Be certain that any vtam acbs 
owned by this task have been closed before issuing dsifre aq = yes. NetView will 
free all queued storage with one invocation of dsifre aq=yes (both mainline and 
exit storage). Some macros may require queued storage; therefore, the subtask 
may not issue any NetView macros after releasing the queued storage. 

Additional Considerations 

Special Requirements for IRB Exits: User-written irb exits that invoke NetView 
macro services require the following special processing: 

• On entry, if the tvbinxit is not on, then set it on. If the tvbinxit bit is already set 
to on, increment tibmuxit by 1. 

• On exit, if tibmuxit is zero, then clear the tvbinxit bit. However, if tibmuxit is 
greater than zero, then you must decrement it by 1. 
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Displaying Status: The list command displays the status of a subtask on an 
operator's terminal. For opt subtasks, in addition to status, a header line and the 
contents of tvbopid and tvblunam are also displayed. Status is determined by the 
following tvb bit fields in the following order: 

1. tvbrcvry — recovering 

2. tvblgoff — stopping 

3. tvbactv — active 

4. tvblgon — starting 

5. None of the above — inactive. 

The subtask can also create its own status display. 

VTAM Outage Processing: User-written code (exit routines, command processors, 
and subtasks) requiring vtam will get error codes whenever vtam is inactive. User- 
written subtasks that require vtam must provide for the case of vtam ending without 
NetView ending in these ways. 

• If your task opens a vtam acb, you can code a tpend exit for vtam that is called 
when vtam ends. Your tpend exit can postTVBTECB to signal task termination to 
begin. 

• If your task requires vtam to be active and does not open an acb, you can still 
be notified. Set the tvbautve bit in the tvb for your task. When NetView's main 
task tpend is called (for halt net, quick, for halt net, cancel, and for vtam 
abend), the NetView main task will post tvbtecb for every task that has 

TVBAUTVE Set to 1 . 

• In either case, NetView also provides another bit, tvbautvs, which causes 
NetView main task to reattach your subtask when NetView detects that vtam 
has been reactivated to the point that the main task's acb was opened success- 
fully. Set tvbautvs to 1 for this function. 



Data Services Task (DST) 
Overview 



A data services task is a set of NetView interfaces built on top of the optional task 
base. NetView provides a subtask processing module (dsizdst) along with the 
following: 

• An initialization exit interface 

• A Data Services Command Processor (dscp) interface that provides the fol- 
lowing services: 

- A cnm data services macro interface (dsizcsms) to request and send data 
across the Communication Network Management interface. 

- An interface to allow a command processor to receive unsolicted cnm data 

- A vsam data services macro interface (dsizvsms) to put and get records 
from a pre-defined vsam dataset. 

• Various user exit interfaces 
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Installation 



Initialization 



A task statement for the subtask must be coded in the dsidmn member of the 
dsiparm data set. This task statement follows the same format as the optional task 
task statement with the following exceptions: 

1. The mod keyword must specify dsizdst as the subtask processing module. 
dsizdst is provided by NetView and provides the necessary initialization, proc- 
essing, and termination routines to use the dscp interfaces. 

2. The initialization dataset member (specified by the mem keyword) must contain 
dstinit statements to provide various initialization parameters required by 
dsizdst. The statements will be discussed below under their respective inter- 
faces. 

The values of the other task statement keywords have the same meaning as those 
coded for an optional task. 

• pri keyword - Specifies the relative task priority (1-9). 1 is the highest task pri- 
ority that can be assigned, and 9 is the lowest. 

• init keyword - Specifies whether the task is to be started during NetView initial- 
ization (init=y) or via the start command only (init=n). 

• tskid keyword - The task name. Each task in NetView must have a unique task 
name. 



TASK M0D=DSIZDST,TSKID=USERTASK,MEM=USERMEM,PRI=7,INIT=Y 



In the example above, the subtask identification is usertask. usermem is the name 
of the dsiparm member (for mvs) or the file with file type nccflst (for vm) that con- 
tains additional initialization information. The Priority of the subtask is 7, and the 
subtask will be started during NetView initialization. 



For additional details on dstinit statements, see NetView Administration 
Reference. 

DSTINIT Keywords: The following keywords apply to dst initialization processing. 

• funct - The funct keyword specifies which dst services will be required. In all 
cases, the ability to call dscps is provided. The function choices are: 

- other - The dst does not require the cnmi or vsam interfaces. 

— both - Both the vsam and cnmi interfaces are required. 

— cnmi - Only the cnmi interface is required. 

- vsam - Only the vsam interface is required. 

• xitdi - The xitdi keyword specifies the name of the user provided initialization 
exit. The exit is called with the standard NetView user exit interface as docu- 
mented in Chapter 3 on page 31 and is called once for every statement in the 
specified initialization member (mem keyword of task statement). When End- 
Of-File has been reached, userpdb and usermsg will both be 0. For each state- 
ment (except End-Of-File condition), the standard user exit return codes will 
cause the following actions: 
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- userasis (0) - The statement will be processed by the NetView dst module 
(dsizdst). If it is not a valid dstinit statement, dsizdst will reject it with an 
error message and continue processing. 

- userdrop (4) - The statement will not be processed by dsizdst. This return 
code should be used if your user exit is going to process the statement 
(you can define your own initialization statements). 

- userswap (8) - The swapped buffer will be processed by dsizdst. If the 
swapped buffer does not contain a valid dstinit statement, it will be 
rejected by dsizdst and processing will continue. 

When returning from the last call (for End-Of-File), any non-zero return code will 
terminate the dst. This should only be done if the initialization process has failed. 

The initialization exit should invoke the dsipush service to define a logoff routine. 
The logoff routine will be invoked during normal or abnormal end of task proc- 
essing (no termination exit is provided). The logoff routine should free any 
resources that the user has acquired. Storage that has been acquired with the 
q=yes option is automatically freed by the dsizdst module. 

Data Services Command Processor 

A data services command processor (dscp) generally performs cnm data services, 
using macro dsizcsms, or vsam data services, using macro dsizvsms, or both ser- 
vices. 

When a dst calls a dscp, the input to the dscp includes the address of a data ser- 
vices request block (dsrb) in the cwbdsrb field. The dsrb function code (dsrbfncd) 
indicates the purpose for which the command was called, dsrbfncd is described 
under "DSRB — Data Services Request Block" on page 129. 

There are two restrictions to observe when writing a dscp: 

• Only commands defined as type=d or type=rd may be called under a dst or 
queued to a dst. Call only user-defined commands directly. Commands called 
from your dscp cannot use NetView macros dsizvsms nor dsizcsms. 

• Use only dsipss type = output or type=immed. Messages sent this way will go to 
the operator who started the task (owner). If the task was started during 
NetView initialization or if the owner has logged off the message is sent to the 
ppt for routing and automation. 

Data services requests are generally sent with hdrmtype = hdrtypei. Operators can 
queue commands using the excmd command, and these commands may be identi- 
fied since they will be hdrtypet, hdrtypeb, or hdrtypqc. You may wish to check the 
hdrmtype field and reject direct operator requests. 

CNM Data Services 

The dst provides access to both solicited and unsolicited cnm data, dsizcsms can be 
issued by a dscp to solicit cnm data from the network. A dscp can be defined to 
receive unsolicited data from vtam. 

An acb with auth = cnm must be defined to vtam with the acb name matching the 
task id of the dst. 
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Unsolicited CNM Data Interface 

vtam provides a default table (istmgcoi) which controls the routing of unsolicited 
cnm rus. You can write a supplemental table (istmgcoo) to override the default 
routing information provided by vtam. The routing information consists of a partic- 
ular ru type and the name of an application which is to receive the particular type 
of data. When a dst is defined with cnmi services, an acb is opened with an acb 
name (the application name) equivalent to the task name as defined by the tskid 
parameter of the dst task definition statement (the one exception is Hardware 
Monitor whose cnmi dst's task name is bnjdserv, but the application name is 
bnjhwmon). If the dst task name is entered as the application name in the vtam 
routing table, the unsolicited data ru will be passed to the unsolicited data services 
command processor for that dst. 

DSTINIT Keywords 

• unsol - Specifies the command verb name of the module that is to serve as the 
unsolicited dscp for this dst. The unsolicited dscp should not issue the 
dsizcsms macro, but may issue the dsizvsms macro. 

• dsrbu - Specifies the number of unsolicited dsrbs which are to be allocated to 
this dst. If unsolicited cnm data isn't going to be processed by this dst, then 
this value should be set to zero. If the unsolicited dscp is going to issue the 
dsizvsms macro, then this value should be set to the number of concurrent 
dsizvsms requests which are to be allowed. If the unsolicited dscp is not going 
to issue the dsizvsms macro, then this value should be set to 1. 

Note: To issue dsizvsms also, funct=both must be specified. 

DSCP Interface: When the unsolicited dscp receives control, the dsrbfncd field will 
contain the dsrbfuns (unsolicited) function code, dsrbubuf will be zero, and 
dsrbcusb will contain the address of a NetView buffer containing the unsolicited 
data. The ru starts at the offset specified in hdrtdisp and the ru length is in 
hdrmleng. If a Deliver header is present, it will be considered part of the data (i.e. 
- hdrtdisp will point to the start of the Deliver header). See the VTAM Program- 
ming book for more information. 

The return codes on entry to the unsolicited dscp are as follows: 

Meaning 

Successful completion. 

User exit rejected the Deliver ru. hdrmleng is 

set to zero. 
00 20 Data has been truncated. The length of the 

Deliver ru was greater than the length of the 

buffer, hdrmleng is set to the truncated length. 
00 24 Data was truncated after the user exit returned 

with a return code of userswap. hdrmleng is set 

to the truncated length. 

Solicited CNM Data Interface 

The dsizcsms macro can be invoked by a dscp to acquire Communications Network 
Management data from the network. 

DSTINIT Keyword: dsrbo - Specifies the number of solicited dsrbs that will be 
required by this task and limits the number of concurrent dsizcsms and/or dsizvsms 
requests. This value must be at least 1 (a dscp will not be called unless a solicited 
dsrb is available) and no greater than 862. 
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DSRBRCMA 


DSRBRCMI 


00 


00 


00 


16 



DSRBRCMA 


DSRBRCMI 


00 


00 


00 


04 


00 


08 


00 


16 



DSCP Interface: Acquiring cnm data is a two part process. When the dscp is first 
driven (generally by a command buffer MQsed by an ost task), the dsrbfncd field 
will contain a value of dsrbfnrm. The cwbdsrb field will point to a dsrb that must 
be passed on the dsizcsms macro. The first step is to issue the dsizcsms macro 
with the supplied dsrb. After the macro is issued, register 15 will contain the major 
return code and register will contain the minor return code (additional completion 
information). If register 15 is not zero then the macro has failed. If register 15 is 
then the request has successfully been sent to vtam. At this time, the dscp should 
be exited because the data will be returned on a subsequent invocation of the 
same dscp (this is called a re-drive operation). 

When the dscp is re-driven (the second part of the process), the dsrbfncd code will 
be dsrbfsol. The dsrbrcma (dsrb Major Return Code) and the dsrbrcmi (dsrb 
Minor Return Code) must be checked to see if the request completed successfully. 

Meaning 

Successful completion. 

Negative response was received, dsrbinpt con- 
tains the address of the negative response. 

Insufficient storage to process the request. 

User exit rejected the Deliver ru. hdrmleng is set 

to zero. 
00 20 Data has been truncated. The length of the Deliver 

ru was greater than the length of the buffer. 

hdrmleng is set to the truncated length. 
00 24 Data was truncated after the user exit returned 

with a return code of userswap. hdrmleng is set to 

the truncated length. 
00 28 vtam rejected the request. 

00 32 cnm interface closed due to unrecoverable error. 

00 36 Positive response was received. 

00 44 Cancellation due to timer completion. This code is 

returned only when running with vtam V3R1.1 or 

later. 

If the request completes successfully, the input buffer supplied on the initial 
dsizcsms invocation (input parameter) will contain the received data. The buffer 
will contain a standard NetView buffer header with hdrtdisp containing the offset to 
the start of the data. If the data is preceded by a Deliver ru, hdrtdisp will contain 
the offset to the start of the Deliver ru. 

After the initial invocation of dsizcsms and until the dscp is redriven, the dsrb is 
considered 'in use' and is not available to other dscps (other dscps can run during 
this time frame only if the dsrbo value is greater than 1 and there is a dsrb that is 
'not in use' by another dscp). When the dscp is re-driven, the dsrb is the only 
control block that is the same as on the initial invocation of the dscp. The dsrbuser 
field has been provided for your use and can be used to contain or point to any 
additional environment information that you wish to maintain. 

VSAM Service Interface 

The dsizvsms macro can be invoked by a dscp to perform i/o to a specified vsam 
data set. 

DSTINIT Keywords: The primary and secondary data sets are user-defined and 
are switchable. 

• PDDNM - Specifies the dd name of the primary data set to be used by vsam ser- 
vices. This data set must be allocated prior to starting the dst. 
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• PPASS - Specifies the vsam password to be used when the primary data set 
acb is opened. 

• SDDNM - Specifies the dd name of the secondary data set to be used by vsam 
services. This data set must be allocated prior to starting the dst. The 
NetView switch command is used to control which data set is currently the 
'active' data set. 

• SPASS - Specifies the vsam password to be used when the secondary data set 
acb is opened. 

• MACRF - Specifies local resource sharing. 

• XITVN - Specifies a user exit to receive control when an empty vsam data set 
has been opened for processing. This exit allows you to put an initialization 
record into the data set. 

• XITVI - Specifies a user exit to receive control upon input from the vsam data 
set before the input record is passed to the requesting dscp. 

• XITVO - Specifies a user exit to receive control before output of a record to the 
vsam data set. 

Note: If dsrbo is greater than 1, then NetView does not guarantee that the 
dsizvsms requests for vsam Puts will be processed in the order that they were sub- 
mitted. (The requests will complete asynchronously.) 

DSCP Interface: Like the cnm Interface service (dsizcsms), using dsizvsms is a two 
part process. When the dscp is first driven (generally by a command buffer MQsed 
by an ost task), the dsrbfncd field will contain a value of dsrbfnrm. The cwbdsrb 
field will point to a dsrb that must be passed on the dsizvsms macro. The first step 
is to issue the dsizvsms macro with the supplied dsrb. After the macro is issued, 
register 15 will contain the major return code and register will contain the minor 
return code (additional completion information). If register 15 is not zero then the 
macro has failed. If register 15 is then the request has successfully been sent to 
vsam. At this time, the dscp should be exited because the success or failure of the 
vsam i/o requested will be returned on a subsequent invocation of the same dscp 
(this is called a re-drive operation). When the dscp is re-driven (the second part of 
the process), the dsrbfncd code will be dsrbfvsm. The dsrbrcma (dsrb Major 
Return Code) and the dsrbrcmi (dsrb Minor Return Code) must be checked to see if 
the request completed successfully. 

The return codes are as follows: 

Meaning 

Successful completion. 

User exit processing of vsam input has rejected 

the input, hdrmleng is set to zero. 
00 24 Data has been truncated. User exit returned 

data longer than NetView buffer on rc = 

userswap. hdrmleng is set to the truncated 

length. 
00 28 Invalid return code from user exit. 

08 vsam rpl feedback vsam logical error, indicated 

in dsrbrcmi. See OS/VS VSAM Programmer's 

Guide. 
12 vsam rpl feedback vsam physical error, indicated 

in dsrbrcmi. See OS/VS VSAM Programmer's 

Guide. 

Relevant dsrb fields are as follows: 
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DSRBRCMA 


DSRBRCMI 


00 


00 


00 


16 



DSRBVRPL The address of the vsam rpl that was used for the i/o. 

DSRBVACB The address of the vsam acb for the dst. 

DSRBVDAO The address of the vsam i/o buffer, with a standard 

bufhdr. For get requests, the bufhdr hdrmleng field 
indicates the length of the data read, hdrtdisp contains 
the offset to the data. 

DSRBVKEY The address of the key in the dsrbvdad buffer. 

DSRBVKLN The key length. 

DSRBVRTP Indicates the type of request just completed: 

1 - DSRVGET (VSAM GET) 

2 - DSRVPUT (VSAM PUT) 

3 - DSRVPNT (VSAM POINT) 

4 - DSRVERS (VSAM ERASE) 

5 - DSRVNRQ (VSAM ENDREQ). 

After the initial invocation of dsizvsms and until the dscp is redriven, the dsrb is 
considered 'in use' and is not available to other dscps (other dscps can run during 
this time frame only if the dsrbo value is greater than 1 and there is a dsrb that is 
'not in use' by another dscp). When the dscp is re-driven, the dsrb is the only 
control block that is the same as on the initial invocation of the dscp. The dsrbuser 
field has been provided for your use and can be used to contain or point to any 
additional environment information that you wish to maintain. 

Example of DSCP Design 

A dscp can be used to solicit communication network management (cnm) data from 
a resource in the network and record the results on a vsam data set. To accom- 
plish this, dscp processing can follow the steps that are listed below and refer- 
enced in Figure 12 on page 93. 

1. A dst subtask that receives an ifrcodcr buffer calls the dscp with a function 
code of "initial call." The dscp issues dsizcsms to solicit the cnm data. The dscp 
returns to the caller. Q 

2. The dscp is redriven 3 with a function code of "solicited cnm data." The dscp 
issues dsizvsms to write the data to the vsam data set. The dscp returns to the 
caller. Q 

3. The dscp is redriven with a function code of "vsam i/o completed." If more than 
one cnm buffer is needed, the dscp issues another dsizcsms to retrieve the 
buffer. The dscp returns to the caller. Q 

4. Steps 2 and 3 repeat alternately until the dscp has retrieved all of the data. 

5. When the dscp is redriven for completion of the last vsam put, it sends a com- 
pletion message and returns control to the dst. Since neither dsizcsms nor 
dsizvsms was issued, the dsrb will not be redriven. Processing for the dscp 
ends. [] 



3 When a dscp is redriven, its input control blocks and fields, except for the dsrb, may be completely different than 
those used in its previous invocation. 
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Figure 12. Structure of a Data Services Command Processor 
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Figure 13 shows one way you can structure data services requests. This example 
starts with an initial operator command. This invokes the dscp using dsimqs with 
an ifrcodcr buffer. When the dscp has obtained vsam or cnm data to be presented, 
it may do either of the following: 

• Send the message data to the terminal (for standard or title-line output) 

• Invoke a presentation services command processor (pscp) to present the data 
(for full-screen output). 
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Figure 13. Example of Program Design for Data Services Requests 

The command uses dsiget to obtain storage. The address of this storage can be 
saved in dsrbuser, or dsipush can save it as a named storage pointer. This estab- 
lishes and maintains data from one dscp call to the next. 

If the dscp does not use the parse buffer pdb, you can improve the performance by 
specifying parse=n on the cmdmdl statement defining the dscp. In this case, the 
command buffer is not parsed and no pdb is provided to the command processor. 
(parse=n applies only to commands invoked by a dst.) 

An operator may have one or more pending dst requests. You can use the list dst 
command to list active dst requests. 

User Defined Services 

Command processors defined as type=d or type=rd can be invoked under the dst 
to perform user functions. They will be invoked with a standard NetView command 
processor interface (Register 1 will point to a dsicwb control block). If no parsing of 
the command buffer is required, then parse = n should be specified on the respec- 
tive cmdmdl statement for the dscp (this will improve performance). 
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Termination 

You should issue dsipush to set up a logoff routine in your initialization exit. If the 
dst is terminated (normally or abnormally), the logoff routine will be invoked and 
you should clean up any storage or resources you have acquired. Queued storage 
will be automatically released by the dsizdst module prior to termination. 



Template for an Optional Task 

The following template illustrates basic initialization, ecb loop, and termination 
processing required by optional tasks. This template is available on-line in the 
NetView sample library (syslcnmsamp) as CNMS4277. 
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AOPTTSK CSECT 



*********************************************************************** 
*********************************************************************** 



*** 

*** IEBCOPY SELECT MEMBER' ((CNMS4277, AOPTTSK, R)) 
*** 

*** (C) COPYRIGHT IBM CORP. 1989 
*** 

*** 

*** MODULE NAME: AOPTTSK 



*** 
*** 
*** 
*** 
*** 
*** 
*** 
*** 



*** 

*** FUNCTION: USER DEFINED OPTIONAL SUBTASK. THIS SUBTASK WAITS *** 
*** ON TASK TERMINATION AND THE MESSAGE QUEUE ECBS. MESSAGES *** 
CAN BE PLACED ON THIS TASKS MESSAGE QUEUE BY: 



*** 



*** 



*** 



*** 



1. USE EXCMD COMMAND *** 

2. USER WRITTEN COMMAND PROCESSOR WHICH SENDS BUFFER *** 
VIA DSIMQS MACRO WITH A BUFFER TYPE OF T. 



*** 
*** 

*** VTA nCTMOC MATOn UTTU A OIICCCD TVDC flC >T' *** 

*** *** 

*********************************************************************** 
*********************************************************************** 
*** *** 

*** INSTALLATION: *** 



*** 
*** 
*** 



1. ASSEMBLE AND LINKEDIT INTO NETVIEW LOAD LIBRARY 



*** 2. ADD TASK STATEMENT TO DSIDMN MEMBER IN DSIPARM 

*** 



TASK MOD=AOPTTSK,TSKID=MYTASK, PRI=8, INIT=N 



*** 
*** 

*** NOTE: TASK CAN BE STARTED AND STOPPED BY ISSUING 
*** START TASK=MYTASK OR STOP TASK=MYTASK. 



*** 
*** 
*** 
*** 
*** 
*** 
*** 
*** 
*** 



*** *** 

*** *** 

*********************************************************************** 

* INPUT: REG 1 - ADDRESS OF TASK VECTOR BLOCK (DSITVB) * 

* REG13 - ADDRESS OF CALLER'S SAVE AREA * 



REG14 
REG15 



RETURN ADDRESS 
ENTRY ADDRESS 



OUTPUT: 



REGISTERS: 
REG 



REG14 - RESTORED UPON RETURN 



REG 15 RETURN CODES: 

- SUCCESSFUL 



NETVIEW MACROS: 

DSICBS 

DSIDATIM 

DSIFRE 

DSIGET 

DSILCS 

DSIWAT 



CONTROL BLOCK SERVICE 
DATE AND TIME SERVICE 
FREEMAIN STORAGE SERVICE 
GETMAIN STORAGE SERVICE 
LOCATE CONTROL BLOCKS 
ECB WAIT SERVICE 



*********************************************************************** 



Figure 14 (Part 1 of 11). Template for an Optional Task 
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********************************************************************** 





EJECT 








RO 


EQU 









Rl 


EQU 


1 






R2 


EQU 


2 






R3 


EQU 


3 






R4 


EQU 


4 






R5 


EQU 


5 






R6 


EQU 


6 




WORKAREA BASE REGISTER 


R7 


EQU 


7 




DSIMVT BASE REGISTER 


R8 


EQU 


8 




DSITVB BASE REGISTER 


R9 


EQU 


9 




DSITIB BASE REGISTER 


RIO 


EQU 


10 






Rll 


EQU 


11 






R12 


EQU 


12 




BASE REGISTER 


R13 


EQU 


13 






R14 


EQU 


14 






R15 


EQU 
EJECT 


15 








PRINT OFF 








DSICBS DSIMVT, DSISVL.DSISWB 


, DSITIB, DSITVB 




PRINT ON 








USING 


*,R15 








B 


PROLOG 








DC 


C'AOPTTSK 


&SYSDATE. 


AT &SYSTIME.' 


PROLOG 


DS 


OH 








STM 


R14,R12,12(R13) 


SAVE REGS IN CALLERS SAVEAREA 




DROP 


R15 








LR 


R12.R15 




GET EPA FOR BASE REG 



USING A0PTTSK,R12 R12 IS BASE FOR PGM 

*********************************************************************** 

* * 

* ESTABLISH CONTROL BLOCK ADDRESSABILITY * 

* * 

*********************************************************************** 

LR R8.R1 GET TVB ADDRESS 

USING DSITVB, R8 SET UP BASE FOR TVB 

L R9.TVBTIB GET TIB ADDRESS 

USING DSITIB, R9 SET UP BASE FOR TIB 

L R7.TVBMVT GET MVT ADDRESS 

USING DSIMVT, R7 SET UP BASE FOR MVT 

*********************************************************************** 

* * 

* ESTABLISH SAVE AREA * 

* * 

*********************************************************************** 

ST R13.TIBSAVES+4 SAVE CALLERS R13 IN MY SAVEAREA 

LA R2.TIBSAVES POINT R2 TO MY SAVEAREA 

ST R2,8(0,R13) PUT MY SAVEAREA ADDR IN CALLERS 

LR R13.R2 SET UP R13 TO MY SAVEAREA 

*********************************************************************** 

* * 

* CHECK FOR TERMINATION REDRIVE. 

* * 

*********************************************************************** 

TM TVBIND1.TVBTERM WAS I DRIVEN FOR TERMINATION? 

BO TERMINAT YES, GO AND DO TERM PROCESSING 

Figure 14 (Part 2 of 11). Template for an Optional Task 
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***************************************************************** 

* * 

* CALL INITRTN TO PERFORM INITIALIZATION PROCESSING. TVBTERM WILL * 

* BE SET IF ANY ERRORS OCCURED DURING INITIALIZATION. * 

* * 

*********************************************************************** 

BAL R14, INITRTN TELL NETVIEW THAT I'M ACTIVE 

TM TVBIND1, TVBTERM ANY ERRORS? 

BO RETURN YES, EXIT 

*********************************************************************** 

* * 

* SET UP ECB LIST. TERMINATION ECB (TVBTECB) AND THE MESSAGE QUEUE * 

* ECB (TVBMECB) ARE INCLUDED. * 

* * 

*********************************************************************** 

LA Rl, TVBTECB GET ADDRESS OF TERMINATION ECB 

ST Rl.ECBLIST STORE IT IN ECB LIST 

LA Rl, TVBMECB GET ADDRESS OF MESSAGE QUEUE ECB 

ST Rl.ECBLIST+4 STORE IT IN ECB LIST 

01 ECBLIST+4,X'80' MARK END OF LIST 
*********************************************************************** 

* * 

* WAIT ON ECB LIST FOR TERMINATION OR MESSAGE EVENT. * 

* * 

*********************************************************************** 

WAIT EQU * 

DSIWAT ECBLIST=ECBLIST WAIT ON TERMINATION ECB 
*********************************************************************** 

* * 

* CHECK FOR TERMINATION. * 

* * 

*********************************************************************** 

TM TVBTECB, TIBECBPO TASK TERMINATION ECB POSTED 

BZ MESSQ IF NOT, DO THE MESSAGE QUEUE 

XC TVBTECB, TVBTECB CLEAR TERMINATION ECB 

B TERMINAT EXIT 

*********************************************************************** 

* * 

* IF TERMINATION ECB NOT POSTED, ASSUME MESSAGE ECB WAS POSTED. * 

* * 

*********************************************************************** 

MESSQ EQU * 

XC TVBMECB, TVBMECB CLEAR MESSAGE ECB 
*********************************************************************** 

* * 

* COMPARE AND SWAP THE PUBLIC QUEUE (TVBMPUBQ) TO THE PRIVATE QUEUE * 

* (TVBMPRIQ) FOR PROCESSING. * 

* * 

*********************************************************************** 

CHEKQ EQU * 

SLR RO.RO ZERO THE SWAP REGISTER 

L R3, TVBMPUBQ LOAD COMPARAND REGISTER 

CS R3.R0, TVBMPUBQ CS ZERO ON THE QUEUE 

BNE CHEKQ RETRY IF TVBMPUBQ CHANGED 

Figure 14 (Part 3 of 11). Template for an Optional Task 
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******************************************************************* 

* * 

* REVERSE THE PRIVATE QUEUE ORDER SO THAT THE MESSAGES ARE PROCESSED * 

* IN THE CORRECT ORDER. * 

* * 

*********************************************************************** 

USING BUFHDR.R3 

REVQ EQU * 

L Rl.HDRNEXTM REVERSE 

ST RO.HDRNEXTM THE 

LR R0.R3 QUEUE 

LTR R3.R1 ORDER. TEST FOR END OF Q 

BNZ REVQ CONTINUE IF NOT END OF Q 

ST ' RO.TVBMPRIQ POINT PRIVATE ANCHOR AT FIFO Q 

DROP R3 
*********************************************************************** 

* * 

* CALL PROCMSG TO PROCESS THE PRIVATE QUEUE. * 

* * 

*********************************************************************** 

BAL R14, PROCMSG GO PROCESS THE MQS MESSAGE 

B WAIT GO BACK AND WAIT 

*********************************************************************** 

* * 

* BEGIN TERMINATION PROCESSING * 

* * 

*********************************************************************** 

TERMINAT EQU * 

OC TVBUFLD.TVBUFLD ANY STORAGE TO FREE? 

BZ RETURN NOPE, EXIT 

BAL R14.TERMRTN DO TERMINATION PROCESSING 

DSIFRE LV=4096,A=TVBUFLD FREE STORAGE 

LTR R15.R15 DID I FREE THE STORAGE? 

BZ FREEQ YES, FREE QUEUED STORAGE 

MVC MESSAGE(L'FRUFAIL),FRUFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'FRUFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

*********************************************************************** 

* * 

* FREE ALL QUEUED STORAGE. *■ 

* * 

*********************************************************************** 

FREEQ EQU * 

DSIFRE AQ=YES FREE QUEUED STORAGE 

LTR R15.R15 DID IT WORK? 

BZ RETURN YES, QUEUED STORAGE WAS FREED 

MVC MESSAGE(L'FRQFAIL),FRQFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'FRQFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

Figure 14 (Part 4 of 11). Template for an Optional Task 
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***************************************************************** 

* * 

* RETURN TO CALLER. * 

* * 

*********************************************************************** 

RETURN EQU * 

L R13.TIBSAVES+4 RESTORE CALLERS SAVEAREA ADDR 

SLR R15.R15 CLEAR RETURN CODE REGISTER 

L R14,12(R13) RESTORE RETURN ADDRESS 

LM RO,R12,20(R13) RESTORE REGISTERS 

BR R14 RETURN 

EJECT 
*********************************************************************** 

* * 

* END OF MAINLINE CODE. SUBROUTINES FOLLOW. * 

* * 

*********************************************************************** 
*********************************************************************** 

* * 

* PROCMSG: PROCESSES MESSAGE BUFFERS ON THE PRIVATE QUEUE. * 

* * 

*********************************************************************** 

PROCMSG EQU * 

ST R14.RPR0CMSG SAVE RETURN ADDRESS 

B PROCMSG3 CONTINUE 

*********************************************************************** 

* * 

* IF SUBTASK IS TERMINATING THEN SKIP WTO AND FREE THE MESSAGE BUFFER * 

* * 

*********************************************************************** 

PROCMSG1 EQU * 

TM TVBIND1JVBTERM IS SUBTASK TERMINATING? 

BO PR0CMSG2 YES, ONLY FREE BUFFERS 

*********************************************************************** 

* * 

* PROCESS THE MESSAGE BUFFER HERE * 

* * 

*********************************************************************** 

L R3.TVBMPRIQ GET ADDRESS OF 1ST BUFFER 

MVC MESSAGE(L'MSGRCV),MSGRCV 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'MSGRCV GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

*********************************************************************** 

* * 

* DEQUEUE MESSAGE * 

* * 

*********************************************************************** 

PR0CMSG2 EQU * 

USING BUFHDR.R3 R3 IS BASE FOR BUFFER HEADER 

L R3.TVBMPRIQ POINT TO FIRST BUFFER 

L R1,HDRNEXTM-BUFHDR(,R3) ANCHOR THE NEXT MESSAGE 

ST Rl.TVBMPRIQ MAKE IT THE FIRST BUFFER 

Figure 14 (Part 5 of 11). Template for an Optional Task 
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******************************************************************* 

* * 

* FREE THE MESSAGE BUFFER * 

* * 
*********************************************************************** 

LH R4,HDRBLENG-BUFHDR(,R3) GET THE BUFFER LENGTH 

DSIFRE R,A=(R3),LV=(R4),SP=0 FREE THE BUFFER 

LTR R15.R15 SUCCESSFUL? 

BZ PR0CMSG3 YES, CONTINUE 

MVC MESSAGE (L'FRMFAIL).FRMFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'FRMFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

*********************************************************************** 

* * 

* CHECK FOR MORE MESSAGE BUFFER * 

* * 
*********************************************************************** 

PR0CMSG3 EQU * 

OC TVBMPRIQ.TVBMPRIQ ANYTHING LEFT? 

BNZ PROCMSG1 YES, KEEP PROCESSING 

*********************************************************************** 

* * 

* EXIT MESSAGE PROCESSING * 

* * 
*********************************************************************** 

PROCMSGX EQU * 

L R14.RPR0CMSG RESTORE RETURN ADDRESS 

BR R14 RETURN 

DROP R3 

EJECT 
*********************************************************************** 

* * 

* THIS ROUTINE PERFORMS INITIALIZATION PROCESSING. A SWB CONTROL BLOCK* 

* IS ALLOCATED AND INITIALIZED, THE TASK IS MARKED AS ACTIVE, AND * 

* A INITIALIZATION MESSAGE IS ISSUED. * 

* * 
*********************************************************************** 

INITRTN EQU * 
*********************************************************************** 

* * 

* CLEAR STORAGE * 

* * 

*********************************************************************** 

XC TVBUFLD.TVBUFLD CLEAR STORAGE POINTER 

XC TIBNDATD.TIBNDATD CLEAR TIB WORKAREA 

XC TIBEDATD.TIBEDATD CLEAR TIB WORKAREA 

Figure 14 (Part 6 of 11). Template for an Optional Task 
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************************************************************* 

* * 

* GET A 4096 BYTE WORK AREA. * 

* * 

*********************************************************************** 

ST R14.RINITRTN SAVE RETURN ADDRESS 

DSIGET LV=4096,A=TVBUFLD,CLEAR=YES GET 4K FOR WORKAREA 

LTR R15.R15 DID I GET THE STORAGE? 

BZ INITRTNO YES, CONTINUE 

MVC MESSAGE (L'GETUFAIL),GETUFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'GETUFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

01 TVBIND1.TVBTERM SET TERMINATION FLAG 

B INITRTNX EXIT 

*********************************************************************** 

* * 

* ISSUE DSILCS TO ACQUIRE A SERVICE WORK BLOCK (SWB). * 

* * 

*********************************************************************** 

INITRTNO EQU * 

DSILCS CBADDR=SWBADDR,SWB=GET GET A SWB CONTROL BLOCK 

LTR R15.R15 DID I GET A SWB? 

BZ INITRTN1 YES, GO INITIALIZE SWB 

MVC MESSAGE(L' SWBFAIL) .SWBFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L' SWBFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

01 TVBIND1JVBTERM SET TERMINATION FLAG 

B INITRTNX EXIT 

*********************************************************************** 

* * 

* ENQ ON TVB CHAIN * 

* * 

*********************************************************************** 

INITRTN1 EQU * 

USING DSISWB.R1 Rl IS BASE FOR SWB 

L Rl.SWBADDR GET ADDRESS OF SWB 

ST R9.SWBTIB PUT TIB ADDRESS IN SWB 

DROP Rl 

MVC ENQDEQ(ENQDEQL),LENQDEQ INITIALIZE ENQDEQ LIST 

ENQ (MVTNCCFQ , MVTTVBRN , E , 18 , STEP) , MF= ( E , ENQDEQ) 

LTR R15.R15 ENQ OKAY? 

BZ INITRTN2 YES, CONTINUE 

MVC MESSAGE (L'ENQFAIL) .ENQFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl, L'ENQFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

01 TVBIND1.TVBTERM SET TERMINATION FLAG 

B INITRTNX EXIT 

*********************************************************************** 

* * 

* UPDATE TASK NAME AND SET TASK IS ACTIVE FLAG WHILE ENQ ACQUIRED * 

* * 

*********************************************************************** 

INITRTN2 EQU * 

MVC TVBOPID.TVBLUNAM UPDATE NCCF TABLE WITH TASKID 

01 TVBIND3.TVBACTV INDICATE THAT I'M ACTIVE 

Figure 14 (Part 7 of 11). Template for an Optional Task 



102 NetView Customization: Assembler 



********************************************************************** 

* * 

* RELEASE ENQ ON TVB CHAIN. TASK IS NOW CONSIDERED ACTIVE. * 

* * 

*********************************************************************** 

MVC ENQDEQ(ENQDEQL) .LENQDEQ INITIALIZE ENQDEQ LIST 

DEQ (MVTNCCFQ.MVTTVBRN, 18, STEP) ,MF=(E, ENQDEQ) 

LTR R15.R15 DEQ OKAY? 

BZ INITRTN3 YES, CONTINUE 

MVC MESSAGE(L'DEQFAIL),DEQFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'DEQFAIL GET ADDRESS OF INITIALIZATION MSG 

BAL R14.SENDMSG GO DISPLAY INITIALIZATION MESSAGE 

01 TVBIND1.TVBTERM SET TERMINATION FLAG 

B INITRTNX EXIT 

*********************************************************************** 

* * 

* DISPLAY INITIALIZATION MESSAGE * 

* * 

*********************************************************************** 

INITRTN3 EQU * 

MVC MESSAGE(L'INITMSG),INITMSG 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'INITMSG GET ADDRESS OF INITIALIZATION MSG 

BAL R14.SENDMSG GO DISPLAY INITIALIZATION MESSAGE 

*********************************************************************** 

* * 

* RETURN TO MAINLINE * 

* * 

*********************************************************************** 

INITRTNX EQU * 

L R14.RINITRTN RESTORE RETURN ADDRESS 

BR R14 EXIT 

EJECT 
*********************************************************************** 

* * 

* THIS ROUTINE PERFORMS TERMINATION PROCESSING. THE TASK IS MARKED * 

* AS INACTIVE, A TERMINATION MESSAGE IS ISSUED, AND THE SWB CONTROL * 

* BLOCK IS FREED. * 

* * 

*********************************************************************** 

TERMRTN EQU * 

ST R14.RTERMRTN SAVE RETURN ADDRESS 

Figure 14 (Part 8 of 11). Template for an Optional Task 
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**************************************************************** 

* * 

* ENQUE ON TVB CHAIN PRIOR TO MARKING TASK INACTIVE * 

* * 

*********************************************************************** 

MVC ENQDEQ(ENQDEQL),LENQDEQ INITIALIZE ENQDEQ LIST 

ENQ (MVTNCCFQ,MVTTVBRN,E,18,STEP) ,MF-(E, ENQDEQ) 

LTR R15.R15 

BZ TERMRTN1 

MVC MESSAGE (L'ENQFAIL),ENQFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'ENQFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

TERMRTN1 EQU * 

MVC TVB0PID,=8XL1'40' MAKE THIS TASK INACTIVE 

NI TVBIND3JVBACTV MARK TASK AS INACTIVE 

MVC ENQDEQ (ENQDEQL) .LENQDEQ INITIALIZE ENQDEQ LIST 

DEQ (MVTNCCFQ,MVTTVBRN, 18, STEP), MF=(E, ENQDEQ) 

LTR R15.R15 DEQ OKAY? 

BZ TERMRTN2 YES, CONTINUE 

MVC MESSAGE(L'DEQFAIL),DEQFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'DEQFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

TERMRTN2 EQU * 

OC SWBADDR.SWBADDR IS THERE AN SWB? 

BZ TERMRTNX NO, EXIT 

MVC MESSAGE (L'TERMMSG) JERMMSG 

MVC MESSAGE+7(8),TVBLUNAM GET TASK ID 

LA Rl, L'TERMMSG GET ADDRESS OF TERMINATION MSG 

BAL R14.SENDMSG GO DISPLAY TERMINATION MESSAGE 

*********************************************************************** 

* * 

* FREE ACQUIRED SWB * 

* * 

*********************************************************************** 

DSILCS CBADDR=SWBADDR,SWB=FREE 

XC SWBADDR.SWBADDR CLEAR SWB ADDRESS 

LTR R15.R15 WAS SWB FREED? 

BZ TERMRTNX YES, EXIT 

MVC MESSAGE(L'SWBFFAIL),SWBFFAIL 

MVC MESSAGE+7(8),TVB0PID GET TASK ID 

LA Rl.L'SWBFFAIL GET MESSAGE ADDRESS 

BAL R14.SENDMSG DISPLAY MESSAGE 

Figure 14 (Part 9 of 11). Template for an Optional Task 
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******************************************************************* 

* * 

* FREE ALL QUEUED STORAGE AND RETURN * 

* * 

*********************************************************************** 

TERMRTNX EQU "* 

L R14.RTERMRTN RESTORE RETURN ADDRESS 

BR R14 RETURN 

EJECT 
*********************************************************************** 

* * 

* THIS ROUTINE SENDS A MESSAGE TO THE OPERATOR THAT STARTED THIS * 

* TASK. IF THAT FAILS, THEN THE MESSAGE IS SENT TO THE AUTHORIZED * 

* RECEIVER. * 

* * 

*********************************************************************** 

SENDMSG EQU * 

ST R14.RSENDMSG SAVE RETURN ADDRESS 

USING BUFHDR.R2 R2 IS BASE FOR BUFFER HEADER 

LA R2, BUFFER GET ADDRESS OF BUFFER 

STH Rl.HDRMLENG PUT MESSAGE LENGTH IN BUFFER 

LA Rl.BUFHDRND-BUFHDR GET OFFSET TO MSG TEXT 

STH Rl.HDRTDISP MOVE MESSAGE OFFSET TO BUFFER 

AH Rl.HDRMLENG MSG LEN+HDRTDISP 

STH R1,HDRBLENG MOVE BUFFER LENGTH TO BUFFER 

MVC HDRD0MID(8),MVTCURAN MOVE DOMAIN ID TO BUFFER 

MVI HDRMTYPE.HDRTYPEU INDICATE A USER MESSAGE 

DSIDATIM AREA=DATETIME , FORMAT=BINARY 

L Rl.DATETIME+4 GET TIME 

ST Rl.HDRTSTMP PUT TIME IN BUFFER 

L Rl.SWBADDR GET SWB ADDRESS 

DSIMQS SWB=(R1),BFR=(R2),TASKID=TIBMSGNM SEND TO STARTER 

LTR R15.R15 DID IT WORK? 

BZ SENDMSGX 

DSIMQS SWB=(R1) ,BFR=(R2) ,AUTHRCV=YES 

SENDMSGX EQU * 

L R14.RSENDMSG RESTORE RETURN ADDRESS 

BR R14 RETURN 

*********************************************************************** 

* * 

* END OF CODE. * 

* * 

*********************************************************************** 

EJECT 
LTORG 

Figure 14 (Part 10 of 11). Template for an Optional Task 
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************************************************************** 

* * 

* THESE MESSAGES COULD BE SET UP IN A MESSAGE DEFINITION MODULE * 

* OR IN A MESSAGE DISK MEMBER. SEE ABLDMSG FOR AN EXAMPLE OF USING * 

* DSIMBS TO CONSTRUCT MESSAGES. * 



*********************************************************************** 

TASK IS READY AND WAITING FOR WORK' 

TASK IS TERMINATED' 

DSIFRE FAILED FOR USER STORAGE' 

DSIFRE FAILED FOR QUEUED STORAGE' 

MESSAGE RECEIVED' 

DSIFRE FAILED FOR MQS BUFFER' 

DSIGET FAILED FOR USER STORAGE' 

DSILCS FAILED TRYING TO GET A SWB' 

ENQ ERROR' 

DEQ ERROR' 

DSILCS FAILED TRYING TO FREE SWB' 



INITMSG DC 


C'USROOl XXXXXXXX : 


TERMMSG DC 


CUSR999 XXXXXXXX : 


FRUFAIL DC 


CUSRO02 XXXXXXXX : 


FRQFAIL DC 


CUSR003 XXXXXXXX : 


MSGRCV DC 


CUSR004 XXXXXXXX : 


FRMFAIL DC 


CUSROQ5 XXXXXXXX : 


GETUFAIL DC 


CUSR006 XXXXXXXX : 


SWBFAIL DC 


CUSR007 XXXXXXXX : 


ENQFAIL DC 


CUSR008 XXXXXXXX : 


DEQ FAIL DC 


CUSR009 XXXXXXXX : 


SWBFFAIL DC 


CUSR010 XXXXXXXX : 


LENQDEQ ENQ 


(,,,,), MF=L 


ENQDEQL EQU 


*-LENQDEQ 


EJECT 




DSITIB DSECT 




ORG 


TIBNDATD 


DS 


0XL256 


DATETIME DS 


D 


ECBLIST DS 


2F 


RPROCMSG DS 


F 


RINITRTN DS 


F 


RTERMRTN DS 


F 


RSENDMSG DS 


F 


SWBADDR DS 


F 


ENQDEQ DS 


CL(ENQDEQL) 


ORG 


TIBEDATD 


DS 


0XL256 


BUFFER DS 


OF 


DS 


XL(BUFHDRND-BUFHDR) 


MESSAGE DS 


CL80 


END 


AOPTTSK 



Figure 14 (Part 11 of 11). Template for an Optional Task 
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Chapter 6. Writing REXX User Functions 



Introduction 



This chapter explains how to add additional functions or expand or replace those 
rexx functions that already exist in the NetView/REXx environment. The process for 
mvs/xa is very similar, but for more specific mvs/xa information, refer to the REXX 
Reference. 

Both the vm and the mvs/xa environments use the dsirxebs macro described in 
Chapter 8 to obtain storage for an evaluation block. 

Overview of User-Written Functions 

External functions can be written that allow you to extend the capabilities of the 
rexx language. You can write functions that supplement either the built-in func- 
tions or the functions that are provided. You can also write a function that will be 
used in place of a function already provided. For example, if you want a new sub- 
string function that performs differently from the substr built-in function, you can 
write your own substring function and name it string. Users at your installation 
can then use the string function in their rexx command lists. 

NetView supports three types of function package directories. Basically, there are 
no differences between the three types. They are as follows: 

• dsirxupd - User packages, which are function packages that an individual user 
may write to replace or supplement certain system-provided functions. When 
the function packages are searched, the user packages are searched before 
the local and system packages. 

• dsirxlpd - Local packages, which are function packages that a system support 
group or application group may write. Local packages may contain functions 
that are available to a specific group of users or to the entire installation. 
Local packages are searched after the user packages and before the system 
packages. 

• System packages, which are function packages that have been written by 
NetView. System packages are searched after any user and local packages. 

To provide new functions or change existing functions, there are several steps you 
must perform. The steps are described and explained in more detail in the fol- 
lowing topics. 

Subroutines can also be included in the function package directories. 

Interface to Functions 

When your code gets control, the function gets a control block called the evaluation 
block (evalblok). The function places the result into the evaluation block, which is 
returned to the language processor. The result in the evaluation block is used in 
the interpretation of the rexx instruction that contained the function. 

To obtain an evaluation block, see the NetView dsirxebs macro description. 
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Entry Specifications 

When the code for the function gets control, the contents of the registers are: 

Register tib address for vm, Environment Block for mvs/xa (tib address is in 

ENVBLOCKJJSERFIELD). 

Register 1 Address of the external function parameter list (efpl) 

Registers 2-12 Unpredictable 

Register 13 Address of a register save area 

Register 14 Return address 

Register 15 Entry point address 

External Function Parameter List 

When the function gets control, register 1 points to the external function parameter 
list, which is described in Table 4. The mapping macro irxefpl for the external 
function parameter list is provided by tso/e. 



Table 4. I 


External Function Parameter List 


Offset 
(Decimal) 


Number 
of Bytes 


Description 





4 


Reserved. 


4 


4 


Reserved. 


8 


4 


Reserved. 


12 


4 


Reserved. 



16 4 The address of the parsed argument list. Each argument is 

represented by an address/length pair. The argument list is 
terminated by X'FFFFFFFFFFFFFFFF'. Table 5 shows the 
format of the argument list. 



20 



The address of a fullword that contains the address of an 
evaluation block (evalblok). The evaluation block is used to 
pass back the result of the function. Table 6 on page 111 
describes the evaluation block. 



Argument List 



Table 5 shows the format of the parsed argument list the function receives at offset 
+ 16 (decimal). The mapping macro irxargtb for the argument list is provided by 

TSO/E. 



Table 5. 


Format of the Argument List 




Offset 
(Dec) 


Number 
of Bytes 


Field Name 


Description 





4 


ARGSTRING_PTR 


Address of argument 1 


4 


4 


ARGSTRING_LENGTH 


Length of arguments 


8 


4 


ARGSTRING_PTR 


Address of argument 2 


12 


4 


ARGSTRINGJ.ENGTH 


Length of argument 2 


16 


4 


ARGSTRING_PTR 


Address of argument 3 


20 


4 


ARGSTRING_LENGTH 


Length of argument 3 



24 



X'FFFFFFFFFFFFFFFF' 
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Evaluation Block 



In the argument list, each argument consists of the address of the argument and its 
length. The argument list is terminated by X'FFFFFFFFFFFFFFFF'. 



Before the function returns control to the language processor, the address of the 
evaluation block (evalblok) is placed at offset +20 of the external function param- 
eter list. The function computes the result and returns the result in the evaluation 
block. 

The evaluation block consists of a header and data, in which you place the result 
from your function. Table 6 shows the format of the evaluation block. 

The mapping macro irxevalb for the evaluation block is provided by tso/e. 



Table 6. 1 


Format of the Evaluation Block 




Offset 
(Decimal) 


Number 
of Bytes 


Field 
Name 


Description 





4 


EVPAD1 


A fullword that contains X '00 ' . This field is 
reserved and is not used. 


4 


4 


EVSIZE 


Specifies the total size of the evaluation block in 
doublewords. 



12 



EVLEN On entry, this field is set to X ' 80000000 * , which 

indicates no result is currently stored in the 
evaluation block. On return, specify the length 
of the result, in bytes, that your code is 
returning. The result is returned in the EVDATA 
field at offset +16. 



EVPAD2 A fullword that contains X'00 1 
reserved and is not used. 



This field is 



16 



EVDATA The field in which you place the result from the 
function or subroutine. The length of the field 
depends on the total size specified for the 
control block in the evsize field. The total size of 
the evdata field is: 

EVSIZE * 8 - 16 



The function must compute the result, move the result into the evdata field (at 
offset + 16), and update the evlen field (at offset +8). If the initial evaluation block 
is too small to hold the complete result, you can use the dsirxebs macro to obtain a 
larger evaluation block, dsirxebs creates the new evaluation block and returns the 
address of the new block. Your code can then place the result in the new evalu- 
ation block. You must also change the parameter at offset +20 in the parameter 
list to point to the new evaluation block. If dsirxebs was used to get the initial eval- 
uation block, dsirxebs will release the evaluation block if its address is provided 
when obtaining the larger evaluation block. 

Functions must return a result. Subroutines are not required to return a result. 
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Directory for Function Packages 

After writing the code for the function, you must create an entry in one of the direc- 
tories. You need a directory entry for each individual function package you want 
defined. 

A function package directory is contained in a load module and can be tailored to 
individual users or local groups. The name of the entry point at the beginning of 
the directory is the function package directory name. The name of the directory is 
specified only on the csect. In addition to the name of the entry point, the function 
package directories define each entry point for the individual functions that are 
part of the function package. The directories consist of two parts: a header fol- 
lowed by individual entries for each function included in the function package. 
Table 7 shows the format of the directory header. Table 8 illustrates the rows of 
entries in the function package directory. 

Table 7. Format of the Function Package Directory Header 

Offset Number Description 

(Decimal) of Bytes 

8 An eight-byte character field that defines the directory. This 

is the name of the directory. For example, you can specify 
dsirxufp, which is one of the "dummy" function package 
names that is provided. The name must be in uppercase and 
left justified. 

8 4 Specifies the length, in bytes, of the header. This is the offset 

from the beginning of the header to the first entry in the 
directory. This must be a fullword binary number equivalent 
to decimal 24. 

12 4 The number of functions defined in the function package (the 

number of rows in the directory). The format is a futlword 
binary number. 

16 4 Reserved 

20 4 Specifies the length, in bytes, of an entry in the directory 

(length of a row). This must be a fullword binary number 
equivalent to decimal 32. 

At offset +0 in the header, specify the name of the function package directory. Two 
"dummy" function package directory names are provided: 

• dsirxufp for a user function package 

• dsirxlfp for a local function package 

Format of Entries in the Directory 

Table 8 shows two rows (two entries) in a function package directory. The first 
entry starts immediately after the directory header. Each entry defines a function 
or subroutine in the function package. The individual fields are described following 
the table. 

Table 8 (Page 1 of 2). Format of Entries in Function Package Directory 

Offset Number Field Name Description 

(Decimal) of Bytes 

8 FUNC-NAME The name of the first function or subroutine 

(entry) in the directory. 
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Table 8 (Page 2 of 2). Format of Entries in Function Package Directory 



Offset 
(Decimal) 


Number 
of Bytes 


Field Name 


Description 


8 


4 


ADDRESS 


The address of the entry point of the func- 
tion or subroutine (for the first entry). 


12 


4 


_. 


Reserved. 



16 



56 



SYS-NAME The name of the entry point in a load 

Reserved in module that corresponds to the function or 

VM. subroutine (for the first entry). Not used by 

VM. 



24 


8 


SYS-DD 
Reserved in 
VM 


The ddname from which the function or 
subroutine is loaded. Not used by vm. 


32 


8 


FUNC-NAME 


The name of the second function or subrou- 
tine (entry) in the directory. 


40 


4 


ADDRESS 


The address of the entry point of the func- 
tion or subroutine (for the second entry). 


44 


4 


— 


Reserved. 



48 8 SYS-NAME The name of the entry point in a load 

Reserved in module that corresponds to the function or 

VM subroutine (for the second entry). Not used 

by vm. 



SYS-DD 
Reserved in 
VM 



The ddname from which the function or 
subroutine is loaded. Not used by vm. 



The following describes each entry (row) in the directory. 

FUNC-NAME 

The eight-character name of the external function or subroutine. This is the 
name that is used in the rexx command list. The name must be in uppercase 
and left justified. 

If this field is blank, the entry is ignored. 

ADDRESS 

A four-byte field that contains the address, in storage, of the entry point of the 
function or subroutine. This address is used only if the code has already been 
loaded. 

If the address is 0, the sys-name and, optionally, the sys-dd fields are used. A 
LOAD will be issued for sys-name from the DD sys-dd. 

If the address is specified, the sys-name and sys-dd fields for the entry are 
ignored. 

For vm, functions and subroutines must be loaded with NetView. 

Reserved 

A four byte field that is reserved. 

SYS-NAME 

An eight-character name of the entry point in a load module that corresponds 
to the function to be called for the func-name. The name must be in uppercase 
and left justified. 
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If the address is specified, this field can be blank. If an address of is speci- 
fied and this field is blank, the entry is ignored. 

Not used by vm. See "ADDRESS" above. 

SYS-DD 

An eight-character name of the dd from which the function or subroutine is 
loaded. The name must be in uppercase and left justified. If the address is 
and this field is blank, the module is loaded from the link list. 

Not used by vm. See "ADDRESS" above. 

Example of a User Function Directory 

Figure 15 shows an example of a user function directory. The example is 
explained following the figure. 



DSIRXUFP CSECT 

DC CL8'DSIRXUFP' 



DC 


FL4'24' 


DC 


FL4'4' 


DC 


FL4'G' 


DC 


FL4'32' 


DC 


CL8'MYF1 


DC 


FL4'0' 


DC 


FL4'0' 


DC 


CL8'ABCFUN1 ' 


DC 


CL8' 


DC 


CL8'MYF2 


DC 


FL4'G' 


DC 


FL4'0' 


DC 


CL8'ABCFUN2 ' 


DC 


CL8' 


DC 


CL8'MYS3 


DC 


AL4(ABCSUB3) 


DC 


FL4'0' 


DC 


CL8'ABCFUN3 ' 


DC 


CL8' 


DC 


CL8'MYF4 


DC 


VL4(ABCFUNC4) 


DC 


FL4'0' 


DC 


CL8' 


DC 


CL8' 


SPACE 2 


END 


DSIRXUFP 



String identifying directory 

Length of header 

Number of rows in directory 

Word of zeros 

Length of directory entry 

Start of definition of first entry 

Name used in command list 

Address of preloaded code 

Reserved field 

Name of entry point 

Reserved 

Start of definition of second entry 

Name used in commmand list 

Address of preloaded code 

Reserved field 

Name of entry point 

Reserved 

Start of definition of third entry 

Name used in command list 

Address of preloaded code 

Reserved field 

Name of entry point 

Reserved 

Start of definition of fourth entry 

Name used in command list 

Address of preloaded code 

Reserved field 

Name of entry point 

Reserved 



Figure 15. Example of a Function Package Directory 

In Figure 15, the name of the function package directory is dsirxufp, which is one 
of the "dummy" function package directory names provided. Four entries are 
defined in this function package: 

• myfi, which is an external function 

• myf2, which is an external function 

• MYS3, which is a subroutine 
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• myf4, which is an external function 

For mvs/xa: If the external function myfi is called in a rexx command list, the load 
module with entry point abcfuni is loaded from dd functddl If myf2 is called in a 
rexx command list, the load module with entry point abcfun2 is loaded from the 
linklist because the sys-dd field is blank. 

For vm; If the address is zero 0, processing will continue as if the entry was not 
found. 

The load modules for MYS3 and myf4 have been preloaded. The MYS3 subroutine and 
the MYF4 function have been assembled in a different object module but have been 
link edited as part of the same load module as the directory. The assembler, 
linkage editor, and loader have resolved the addresses. 

When NetView is initialized, the load modules containing the function package 
directories for the environment are automatically loaded. The modules for the 
external functions and subroutines are loaded when a rexx command list calls the 
function or subroutine. All modules that are loaded remain loaded until the last 
rexx command list executing under the task under which the modules were loaded 
finishes executing. 
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Chapter 7. Control Block Reference 



This chapter describes control block fields related to customization interfaces. The 
other fields which may appear in control block mapping macros are considered the 
NetView program's internal use control information and are not to be used as a 
programming interface. 

NetView control blocks and buffers passed to user exits and command processors 
are intended for readonly use and should not be altered, with the exception of 
fields specifically designed as user fields, such as tvbufld, cwbsavea, and 

CWBADATD. 
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ART 



ART — Authorization and Routing Table 



The authorization and routing table (art) is a mapping consisting of multiple 
entries. Each entry includes the name of a vtam resource as defined to NetView 
and indicators to define those spans for which the resource name is defined. 

The mapping of the authorization and routing table is as follows: 



Field Name 


Length 


Description 


ARTCBH 


8 


Control block header. 


ARTTABLE 


* 


Multiple entries. 


ARTENTRY 




Format of each dsiart entry. 


ARTNAME 


8 


Resource name. 


ARTIND 


1 


Indicator flags 

X'80' - This entry is active. 



ARTSDEF 



Variable length bit string, where each bit corresponds to a rela- 
tive entry in dsisnt. If a bit is on (1), the resource is in the span 
at the relative position in the snt. 
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BUFHDR 



BUFHDR - Buffer Header 



All message and command buffers must have an initialized buffer header (bufhdr) 
preceding the buffer text, bufhdr describes the buffer's size and usage, as well as 
the origin of the message or command. The items marked with an asterisk (*) in 
Figure 16 are the bufhdr fields you must initialize. 

bufhdr is a separate dsect contained in the task information block (tib). To obtain 
the bufhdr dsect, use macro dsicbs to include the tib control block. 

bufhdr is the only NetView control block that does not have the dsi prefix in its 
name. 





Standard Buffer Header 






0(0) 


HDRMLENG 
Message Length 


HDRBLENG * 

Total Length of Buffer 


4(4) 


HDRIND * 
Line Type 


HDRMTYPE 
Message Type 


HDRTDISP 

Displacement to the First Character 

of the Text from Start of Header 


8(8) 


HDRTSTMP 
Time Stamp Field 


12(C) 


HDRDOMID * 
Domain Identification 






0(14) 


Reserved Area 



Must be initialized by user before write operation 



BUFHDR Extension (HDRMCEXT) (used by DSIMQS Macro) 



24 (18) 



28 (1C) 



HDRNEXTM 
Chain Field 



HDRSENDR 

Operator ID of Sending Subtask 



Figure 16. Buffer Header (BUFHDR) 
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BUFHDR 



An initialized bufhdr has the fields set as follows: 



Table 9 (Page 1 of 2). Control Block Fields 



Field Name 



Length Description 



BUFHDRND 



HDRBLENG 



HDRDOMID 



HDRIND 



HDRMCEXT 



HDRMLENG 



Label at the end of bufhdr for use in computing the length, in 
bytes, of bufhdr. 

2 The length, in bytes, of the entire buffer: header, text, and 

unused space. This length is used if the buffer is to be released 
with macro dsifre. It is a number between and 32767 bytes. 

8 The identifier of the domain that originated the message. This 

field is displayed and logged. The domain identifier under 
which a particular program is running is shown in the mvtcuran 
field of the main vector table (mvt). It is recommended that the 
value of hdrdomid equal the value of mvtcuran. mvtcuran is an 
eight-byte field that contains a domainid (five or fewer bytes) 
and is padded with blanks (the rightmost three bytes are 
reserved). 

1 This field is normally set to zero except when 

hdrmtype =hdrtypej, hdrtypek, or hdrtypel. If hdrmtype=j, k, or 
l, then: 

HDRLNCTL TYPE = CONTROL LINE 
HDRLNLBL TYPE = LABEL LINE 
HDRLNDAT TYPE = DATA LINE 
HDRLNEND TYPE = DATA END LINE 

12 An extension that is appended to the bufhdr when a buffer is 

transferred from one subtask to another. Macro dsimqs 
bfrflg = no builds this extension when it creates a buffer copy 
for the destination task. If you want to pass the actual buffer 
with dsimqs bfrflg=yes, you must build the extension and ini- 
tialize hdrsendr. 

2 The length, in bytes, of the text in the buffer. 



hdrmsg 



Label to indicate the place for text to begin if hdrmcext is 
present. 



hdrmtype 



hdrmsgln o Label at the end of hdrmcext for use in computing the length, in 

bytes, of bufhdr 4- hdrmcext. 

1 Indicates the current usage of the buffer or the origin of the 

command. If the buffer is written using macro dsipss, this char- 
acter is displayed and logged. For a list of values for hdrmtype, 
see Table 10 on page 123. You can use types B, I, L, T, and U 
only. Types B and T are used for commands only. 

4 mlwto buffer chain pointer; points to the next buffer in the 

chain. 

HDRSENDR a 



HDRNEXTM 



HDRTDISP 



HDRTEXT 



The originator's operator id as found in the sender's tvbopid 
field of the task vector block (tvb). 

The offset from the start of the buffer header to the first byte of 
text. 

Label to indicate the place for text to begin if hdrmcext is not 
present. 
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BUFHDR 



Table 9 (Page 2 of 2). Control Block Fields 



Field Name 



Length Description 



HDRTSTMP 



The time that the buffer was created, in the packed decimal 
form X ' hhmmss OC ' , where: 

hh = the hour of the day, from 00 to 23 
mm = the minutes of the hour, from 00 to 59 
ss = the seconds of the minute, from 00 to 59 
0C = a packed decimal sign. 

To obtain values for this field, use dsidatim (see "DSIDATIM 
Date and Time" on page 165). 



Text 



hdrtdisp indicates where the text starts. With a hdrmcext, text 
normally starts at hdrmsg. Without a hdrmcext, text normally 
starts at hdrtext. Text may start beyond these points, but not 
before them. 



Values for HDRMTYPE Fields 

For buffer header hdrmtype, the table below shows the values for the fields. 

Table 10 (Page 1 of 3). Values for HDRMTYPE fields 



Field Value 



Meaning 



hdrtypeb (?) Indicates a command or command list buffer that has display and 

logging suppressed. Not displayed on the operator's screen. Used to 
suppress display and logging of commands entered with a suppression 
character as defined in initialization member dsidmn. Also used to sup- 
press display and logging of command list statements that are preceded 
by this same suppression character. 

hdrtypec (C) Indicates a command or message from a command list. Changes to 

hdrtypeb for suppressed command list statements. Changes to hdrtypqc 
for quiet command. 

hdrtyped (!) Indicates a message from an immediate command processor. Usually 

sent to the screen using dsipsstype=immed. When displayed in the 
immediate message area on the screen, the hdrmtype and domain name 
are not displayed. When received cross-domain, this type of message is 
in the normal output area, along with its domain name and type prefix. 
dsipsstype=immed does not enforce or set hdrtyped. 

hdrtypee (E) Indicates a message from the ssi. This type is not used for title-line 

mode (mlwto), system action, or wtor messages. See also hdrtypek and 
hdrtypey for other forms of ssi messages. 

hdrtypef (F) Indicates a vsam record. Not displayed on the operator's screen. Used 

within the data services task (dst). 

hdrtypeg (G) Indicates a cnmi record. Not displayed on the operator's screen. Used 
within the data services task (dst). 

hdrtypei (I) Indicates an internal function request. This buffer is a formatted inter- 

face within and between tasks. The ifr contains a function number 
(ifrcode) that determines the format and function of the buffer. 

hdrtypej (') Indicates a title-line (mlwto) message originating from NetView itself. 

These buffers must be in a sequence and include a description of 
control, label, data, and end designators. NetView treats these 
sequences of buffers as a single message for presentation and auto- 
mation. 

hdrtypek (") Same as hdrtypej, but for ibm non-NetView code. 

hdrtypel ( = ) Same as hdrtypej, but for non-IBM written code. 
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Table 10 (Pago 2 of 3). Values for HDRMTYPE fields 



Field Value 



HDRTYPEN (-) 



Meaning 



hdrtypem (M) Indicates a message from the NetView message command processor. 



Indicates a regular single buffer message from NetView. 



hdrtypep (P) Indicates a message or command from the ppt. This message type 

appears in the seventh character position of the domain name on the 
operator's screen, and is not the value in hdrmtype. This indicator 
appears in addition to the hdrmtype of the message itself. 

hdrtypeq (Q) Indicates a message from the vtam po« that is a single-buffer unsolicited 
message. See also hdrtypev, hdrtypey, and hdrtypek for other vtam poi 
messages. This message type is not set for messages from vtam 
received on the ssi. 

hdrtyper (R) Indicates that an operator entered the vtam reply command in response 

to NetView wtor number DSI802A. This message type is logged, but does 
not appear on NetView consoles. 

hdrtypes (S) On some user exits interfaces, hdrmtype is set to hdrtypes to indicate a 

swapped buffer. 

hdrtypet (*) Indicates a command issued to NetView from a NetView terminal. This 

message type indicates that the buffer is a command rather than a 
message. ifrcode=ifrcodcr is similar in that the buffer represents a 
command to be executed. Notice that ifrcodcr generally implies an 
internally formatted command, such as between ost and dst tasks. 
hdrtypet generally implies a command buffer as if an operator had typed 
the command, ifrcodcr buffers can contain non-printable data, hdrtypet 
buffers should contain no non-printable text. 

hdrtypeu (U) Reserved for non-IBM users. Cannot be used for action messages (wtor) 

or title-line (mlwto) messages. 

hdrtypev ( ) Indicates a message from the vtam poi that is a single-buffer solicited 

message. See also hdrtypeq, hdrtypey, and hdrtypek for other vtam poi 
messages. This message type is not set for messages from vtam 
received on the ssi. 

hdrtypew ( + ) Indicates an IBM-written single line message. Similar to hdrtypen and 
hdrtypeu. 

hdrtypex (X) Indicates a cross-domain (nnt to ost) command. Allows reverse- 

direction commands, since commands are normally routed from the ost 
to the nnt, for example, with the route command. 

Code running in a nnt task can issue dsipss type = output for a hdrtypex 
buffer, and the corresponding command will be executed in theosT that 
started the session with that nnt. This is useful for sending non- 
formatted (hexadecimal) data from the nnt to an ost for full-screen or 
other formatting. Limited to 256 bytes. Not displayed on the operator's 
screen. 
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Table 10 (Page 3 of 3). Values for HDRMTYPE fields 



Field Value 



Meaning 



hdrtypey (> ) Indicates single-buffer action or wtor. Can be a message from the ssi as 
well as from the vtam poi. These messages remain on the screen until 
an action is taken or the reply is entered. The operator can delete these 
messages by overstriking the > character and pressing enter. The 
message disappears the next time the screen wraps over the text. 

When the hdrtypey flag is set and the ifrauwqe flag is not set, NetView 
looks for a 3-character reply id immediately preceding the message 
number in the message text. If the reply id exists, the message is a vtam 
wtor. Otherwise, the message is treated as a held message (if ifrauwqe 
is zero). If ifrauwqe is set to 1, the ifrauwqd data is checked to see if the 
wqe data indicates a wtor or action message. If wtor is indicated, a 
2-character reply id immediately precedes the message id. If a reply id 
exists, it is delimited from the message id by one space. 

hdrtypez (Z) Similar to hdrtypen, but specifically indicates a message from a data 

services task (dst). 

hdrtypes ($) Indicates a non-displayable data message. Used for data transfer 

between high-level language command procedures. 

hdrtyplt (L) Indicates a trace record. This message type is not displayed on the 

screen or in the NetView Logs. 

hdrtypqc Indicates a command with all synchronous messages suppressed (per- 

('32'X) formance option). 



hdrtypwt (W) 



HDRTYPE1 (V) 



Indicates a message that matched a &wait and was displayed. The w 
appears in the message type field on the screen and in the logs but is 
not in the hdrmtype field in the buffer. The hdrmtype field in the buffer 
contains the original message type. 

Indicates ppqlqg echo of console operator command. 



hdrtype2 (Y) Indicates ppolog copy of console message, suppressed or unsup- 

pressed. 

Example of BUFHDR Usage 

Macro dsidks uses the buffer header when reading a disk data set. You specify the 
blocking factor to block the disk data set. The disk services module dsidrs prefixes 
the physical read buffer with a bufhdr. 

When the first record is requested, macro dsidks reads the first block, hdrtdisp is 
adjusted to indicate the first logical record, dsidks also sets hdrmleng to reflect the 
logical record length. When dsidks is issued for the next logical record, hdrtdisp is 
adjusted to indicate the next logical record until the block is exhausted, dsidks 
reads another physical record; the process starts again from the first logical record 
in the block. 
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CBH — Control Block Header 



The control block header (cbh) must precede all NetView control blocks, except the 
bufhdr and the internal function request (ifr) control block, cbh identifies the 
length and type of control block that follows it, as well as the type of subtask the 
control block represents. 

The relevant fields in the cbh are as follows: 



Field Name 



Length Description 



CBHIO 



A one-character identifier of the control block. 

cbhpob is the identifier for a parse descriptor block (pdb). 



CBHLENG 



CBHTYPE 



A halfword that contains the length of the control block. 
cbhleng represents either the length that is preal located or the 
length that is obtained by macro dsiget. For example, a parse 
descriptor block (pdb) has both a fixed-size portion and a vari- 
able number of entries. For a pdb, cbhleng contains the length 
of both parts. 

The type of subtask that the control block represents. (The tib 
and the tvb each contain this identifier.) The types are the 
primary poi task (ppt), the operator station task (ost), the 
NetView-NetView task (nnt), the hard-copy task (hct), a data 
services task (dst), and the optional subtask (opt). Macro 
dsilcs uses this field for managing control work blocks (cwbs) 
and service work blocks (swbs). In all other cases, this byte is 
reserved. 

cbhhct The identifier used for a tib or a tvb belonging to an 
hct task. 

cbhnnt The identifier used for a tib or a tvb belonging to an 
nnt task. 

cbhoptsk The identifier used for a tib or a tvb belonging to an 
opt task or a dst task. 

cbhost The identifier used for a tib or a tvb belonging to an 
ost task. 

cbhppt The identifier used for a tib or a tvb belonging to the 
ppt task. 
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CWB — Command Work Block 



The command work block (cwb) contains the command processor parameters, a 
save area, and a work area. The relevant fields in the cwb are as follows: 



Field Name 



Length Description 



CWBCBH 



A standard control block header. 



CWBADATD 



CWBBUF 



256 A work area for the command processor. If more storage is 

required, the command processor obtains it with macro dsiget 
and releases it with macro dsifre. The command processor 
must free any storage it obtains. 

4 A pointer to a buffer containing a bufhdr and the command text. 



cwbdsrb 4 Used only by data services command processors (dscps). The 

data services task (dst) initializes this field with the address of 
the data services request block (dsrb). This field contains zero 
for all other command processor types. 

cwbparms 12 A command processor parameter area. Its subfields are 

cwbbuf, cwbpdb, and CWBSWB. 

cwbpdb 4 a pointer to a parse descriptor block (pdb), which is described 

under "PDB — Parse Descriptor Block" on page 146. The pdb 
contains parse information for the command pointed to by 
cwbbuf. If a special type of parse is required, the pdb may be 
reused by the command processor. 



cwbrcode 



On resumption, an lrc receives a return code from a called 
command. 



CWBSAVEA 



72 



A save area that may be utilized by the command processor. 



CWBSWB 



CWBTIB 



A pointer to a service work block (swb) that the command 
processor may use or pass as a parameter to service macros 
or modules. Service macros build parameter lists in the swb 
for the service modules. The swb also contains a task informa- 
tion block (tib) pointer, a parameter list, and a save area for 
use by the service routine, swbs may be reused without re- 
initialization (service routines or macros need only the cbh and 
the tib address). 

The address of the tib for the subtask. The tib and the task 
vector block (tvb) to which the tib field tibtvb is pointed contain 
all the information that relates to the subtask under which the 
command is running. This information contains the operator id, 
the task type, and the task status. 
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DSB — Data Service Block 



The data service block (DSB) contains information used by the disk read service 
routines called when the dsidks macro is issued. The following fields are used by 
the issuer of dsidks to access the records read: 

Field Name Length Description 

dsbbuff 4 jh e address of the i/o buffer containing the record read from 

the data set member. The buffer contains a bufhdr with 
hdrtdisp containing the offset of the requested logical record. 

dsbrec 4 7h e address of the requested logical record read using the 

dsidks macro. 
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DSRB — Data Services Request Block 



The data services request block (dsrb) contains information that a data services 
command processor (dscp) needs to communicate with the dst. It also contains 
work space for the i/o routines. The relevant fields in the dscp are as follows: 



Field Name 



Length Description 



DSRBCBH 



A standard control block header. 



DSRBCUSB 



DSRBFLG 



DSRBFLGS 



DSRBINPT 



The address of a buffer used by the Communication Network 
Management (cnm) interface for unsolicited data. This field is 
used only when the dsrb function code (dsrbfncd) indicates that 
unsolicited data has been received. The buffer contains a 
bufhdr and the data length is in the hdrmleng field of bufhdr. 

The flag settings described below. The bits may be examined 
but not changed. 



dsrbactv = 1 



DSRBINUS = 1 



There is an active transaction using this dsrb. 
A transaction is defined as a request from the 
time of its first arrival at the dscp to the last 
exit of the dscp. When a transaction ends, you 
can reassign the dsrb to another transaction. 

Either the vsam or the cnm interface service 
routine has an active request using this dsrb. 
dsrbinus should not be on when dsrbactv is 
off. 



dsrbtype = 1 The dsrb is used for unsolicited cnm data. 

dsrbtype = o The dsrb is used either for vsam or cnm solic- 
ited data traffic. 



1 The flag settings described below. The bits may be examined 

but not changed. 

dsrbcpms = 1 The alert was generated from the distributed 
host. 

dsrbcpms = o The alert came from the local cnmi. 

dsrbfncd -j Indicator showing the reason that the command processor was 

called. The constants for dsrbfncd are the following: 

dsrbfnrm (1) The first calling of the command processor, 

as the result of an ifrcodcr queued from 
another subtask using dsimqs. 

dsrbfuns (2) The command processor was called to handle 

unsolicited cnm data. 

dsrbfsol (3) Solicited data was received from the cnm 

interface. 

dsrbfvsm (4) A vsam i/o request has completed. 



The address of the cnm interface input buffer. 



dsrboid 



The id of the operator that initiated the transaction. 



DSRBPRID 



DSRBRCMA 



A halfword field that contains a correlation identifier for use by 
the cnm interface. 

The return code for a completed request. It is set after the 
request is completed but before the dscp is called again for 
request completion. This return code value is further explained 
by the minor return code (dsrbrcmi). See "DSCP Interface" on 
page 91 for a description of the return codes. 
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Field Name 



Length Description 



DSRBRCMI 



The minor return code for a completed request. See dsrbrcma. 



DSRBTIB 



The address of the dst task information block (tib). 



DSRBUBUF 



DSRBUSER 



DSRBVRTP 



The address of the original command that was sent to the dst. 
This field is unchanged during the data services transaction. 
This buffer contains a bufhdr and the hdrmcext extension. It 
also has an x'ooo3' ifrcode and hdrtypei. See "IFR — Internal 
Function Request" on page 133. 

A field available for user purposes. If this field is used for a 
storage address, the dst does not free the storage, dsiget 
q=yes allocates storage. Storage may be freed as with any 
subtask that uses dsifre q= yes. If storage is not freed, the 
storage remains allocated until the subtask terminates. 



DSRBVACB 


4 


The address of the vsam acb for the dst 


DSRBVDAD 


4 


The address of the vsam i/o buffer with a standard bufhdr. For 
get requests, the bufhdr hdrmleng field indicates the length of 
the data read, hdrtdisp contains the offset to the data. 


DSRBVECB 


4 


An event control block (ecb) for use by dst when requesting 

VSAM I/O. 


DSRBVKEY 


4 


The address of the key in the dsrbvdad buffer. 


OSRBVKLN 


2 


The key length. 


DSRBVRPL 


4 


The address of the vsam rpl that was used for the i/o. 



An indicator of the type of request just completed: 

1 - DSRVGET (VSAM GET) 

2 - DSRVPUT (VSAM PUT) 

3 - DSRVPNT (VSAM POINT) 

4 - DSRVERS (VSAM ERASE) 

5 - DSRVNRQ (VSAM ENDREQ) 
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ELB — External Logging Block 



The external logging block maps the header information on the buffer passed to the 
xitxl exit. 



Offset 


Length 


Name 


Function 





2 


ELBLENG 


Unsigned length of DSIELB 


2 


2 


ELBRLENG 


Unsigned length of record 


4 


1 


ELBTYPE 


Log type 


5 


3 


ELBLOG 


EBCDIC log type 


8 


4 




Reserved by NetView 



12 Start of record 
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Focal Point Transfer RU Header 



The focal point transfer ru header is part of the cnm router support. All cross- 
domain unsolicited alert data is routed to the cnm router and the focal point 
transfer ru header carries management services information between distributed 
host and the focal point. The header is 44 bytes long and is followed by the nmvt. 
Some of the relevant fields are as follows: 



Offset 


Name 


Length 


Description 





HDR LEN 


2 bytes, 
binary 


Length of the total ru (includes ru header 
and nmvt) 


2 


HDRID 


2 bytes 


AlwayX'1040' 


4 


Reserved 


11 bytes 


For NetView use only 


15 


DOMID LEN 


1 byte, binary 


Originator's domain id length 


16 


DOMAIN ID 


8 bytes, char 


Originator's domain id, padded with 
blanks 


24 


Reserved 


20 bytes 


For NetView use only 



44 



nmvt data 
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IFR — Internal Function Request 



The internal function request (ifr) is a formatted buffer that is transmitted to a sub- 
task's message queue using macro dsimqs. The relevant field in the ifr is as 
follows: 



Field Name 


Length 


Description 




IFRCODE 


2 


Specified as one of the following: 




bytes 


IFRCODCR 


The remainder of the buffer is a command to run. 






IFRCODUS 


The buffer is user-defined and is passed to 
dsiexi3, the message receiver exit routine 
(applies only to an ost or nnt). 






IFRCODPN 


The command is entered from a full-screen 
panel. 






IFRCODAI 


Message automation internal function request 



(aifr). (See "AIFR — Automation Internal Func- 
tion Request" for the subfields of the aifr.) 



AIFR — Automation Internal Function Request 

When ifrcode = ifrcodai, the fields described below are defined starting at the 
location with label ifrparms. For the automation ifr (aifr) the value of hdrtdisp is 
always decimal 36, which includes a standard 24-byte bufhdr and a 12-byte 

HDRMCEXT. 

Note: The aifr is 256 bytes long including the headers. 



Field 
Name 



Length 
or Mask 



Subfield 
orEQU 



Description 



IFRAUIND 



1 byte 



Contains the primary aifr control flags. These 
identify optional fields and describe routing and 
processing actions. 



1... 



IFRAUWQE 



See also ifraussi. When this flag is on, fields in 
ifrauwqd are set from the wqe data received from 
the system. This data is also forwarded to all 
NetView domains by nnts. 

Note: If the ifrautba buffer has 
hdrmtype=hdrtypey and the ifrauwqe flag is on, 
the message must have a two-digit ebcdic reply 
id in front of the message number in the text. 



.1. 



ifraucmd 



Set by message table to indicate that an action is 
in the buffer referenced by ifraucmb. There is a 
separate aifr structure for each command action 
for a particular message. 

Note: ifraucmd and ifrauact must not both be on 
at once. 



.1. 



IFRAUACT 



Indicates that message actions exist in the bits in 
ifrautai. See ifrautai for a description of these. 

ifraucmd and ifrauact must not both be on at 
once. If both ifraucmd and ifrauact are zero, the 
buffer is subject to defaults and overrides. This 
bit must be on to specify force flags in ifrauta4. 



Chapter 7. Control Block Reference 133 



IFR 



Field 
Name 



Length 
or Mask 



Subfield 
orEQU 



Description 



...1 



IFRAUMTB 



Used to control recursion and to prevent sec- 
ondary receiver and copied messages from being 
processed by the message table. This bit can be 
used by dsiexo2a to prevent message table proc- 
essing, ifraumtb is turned off when received from 
an nnt to allow automation of cross -domain mes- 
sages. 

Note: Secondary receiver and copied messages 
are allowed to be automated when received as 
cross -domain messages. 



IFRAUPPT 



1... 



Indicates that a message originated in the ppt. 
This bit replaces the "P" designation in byte 7 of 
hdrdomio. The "P" is only displayed and logged as 
part of the domain name but is never in the buffer 
header. 



IFRAUXDM 



Indicates that a message was received from an 
nnt. This bit can be used to determine if a 
message was from another domain. 



IFRAUDOM 



..1. 



Indicates that this is a system delete message 
request. The system deletes messages by smsgid 
values, by asid and tcb address, or byASio alone. 
This bit must be set only by NetView. 



ifraudfl ifraudfl and ifraudf2 are valid when ifraudom is 
.1 on. ifraudfl = off and ifraudf2=off means delete 

by smsgid. ifraudfl=on and ifraudf2=off means 
delete by asid. ifraudfl=on and ifraudf2=on 
means delete by asid and tcb address. 



IFRAUIN2 



1 byte 



The second byte of indicator flags. 



1. . . ifraudf2 ifraudfl and ifraudf2 are valid when ifraudom is 

on. ifraudfl=off and ifraudf2=off means delete 

by smsgid. ifraudfl = on and ifraudf2=off means 
delete by asid. ifraudfl=on and ifraudf2=on 
means delete by asid and tcb address. 



.1.. 



IFRAUEX2 



Used to prevent calling dsiexo2a a second time. 
This bit is on when dsiexo2a is called to insure that 
dsimqs of buffers from dsiexo2a will not cause 
re-drives. ifrauex2 is reset when received as a 
cross -domain message. This flag also prevents 
calls to dsiexo4 and dsiexo9. 



..1. 



ifraupri 



Indicates that a message was routed using assign 
pri. This is the primary copy of the message and 
is subject to automation. This bit replaces the 
indicator in hdrdomid. This bit prevents assign 
copy. 



ifrausec 



Indicates that a message was routed using assign 
sec This is a secondary copy of the message and 
is not subject to automation. This bit replaces the 
indicator in hdrdomid. ifraumtb is set on also. 
This bit prevents assign copy. 
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Field 
Name 



Length 
or Mask 



Subfield 
orEQU 



Description 



IFRAUCPY 



1... 



Indicates that a message was routed using assign 
copy. This is a secondary copy of the message 
and is not subject to automation. This bit replaces 
the indicator in hdrdomid. ifraumtb is set on also. 
This bit prevents assign copy. 



IFRAUAUT 



,1.. 



Indicates that the buffer was sent using dsimqs 
using authorized receiver routing. This bit 
replaces the indicator in hdrdomid. This bit pre- 
vents ASSIGN COPY. 



ifraudld 



..1. 



Indicates that a message was received from a 
down -level (pre-NetView Release 2) domain. 
The aifr indicators, hdrdomid, and hdrsendr are 
not reliable. 



IFRAUNSL 



...1 



IFRAUSRB 



2 bytes 



Indicates that the message will be routed using 
unsolicited receiver rules. This applies to unso- 
licited ssi traffic, dsimqs authrcv, and unsolicited 
vtam messages. 



IFRAUWID 


4 bytes 


The smsgid value used for dom purposes and to 
collect mlwto buffers. This is a copy of wqe data. 


ifrautcb 


4 bytes 


The job step tcb address for the issuer of the wto. 
It is used as a correlation value and may not be 
an address in the current memory (or machine). 


IFRAUASI 


2 bytes 


The address space id for the issuer of the wto. It 
is used as a correlation value and may not be an 
address space in this machine. 



Provided for the user. It will be initialized to 
zeros when created by NetView and will be 
copied into all copies of the original. It will not be 
changed. 



IFRAUTBA 



4 bytes 



The pointer to data buffers. These are queued 
using hdrnextm to point to the next one. An entire 
mlwto or title-line message is chained to this 
field. The buffers must have standard NetView 
buffer headers and message buffer header exten- 
sions. 



IFRAUTBL 



4 bytes 



Points to the last buffer in the chain and is prima- 
rily intended for allowing buffers to be added to 
the end of a message without the need to scan the 
chain looking for the end. 
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Field 
Name 



Length 
or Mask 



Subfield 
orEQU 



Description 



IFRAUTA1 



1 byte 



ifrautai and ifrauta2 provide the message table 
processing values. They can be set by dsiexo2A 
but are subject to message table and override 
command changes. (See also ifrauta4 force 
flags.) 



00.. 


hold - default 


10.. 


.... HOLD - YES 


01.. 


HOLD - NO 


11.. 


Reserved 


..XX 


Not used 


.... 


00.. syslog - default 


.... 


10 . . SYSLOG - YES 


.... 


01.. SYSLOG -NO 


.... 


11.. Reserved 


.... 


..00 netlog -default 


.... 


. . 10 NETLOG - YES 


.... 


..01 NETLOG -NO 





..11 Reserved 


Option bits 


00.. 


hcylog - default 


10.. 


HCYLOG - YES 


01.. 


HCYLOG - NO 


11.. 


.... Reserved 


..00 


display - default 


..10 


DISPLAY - YES 


..01 


DISPLAY - NO 


..11 


.... Reserved 


.... 


00.. beep -default 


.... 


10.. BEEP -YES 


.... 


01.. BEEP -NO 


.... 


11.. Reserved 


.... 


..xx Not used 



IFRAUTA2 



1 byte 



IFRAUTA3 



1 byte 



More display flags 



1... 



IFRAUAOI 



Indicates whether all or one routing is done as 
stated in the message table. A bit value of 1 Indi- 
cates "all" while a bit value of indicates "one*. 
This flag is internal to message table processing 
and to the dsiexi6 interface. 



.1.. 



IFRAUPFU 



Indicates that a message is full-line mode. This is 
similar to title-line processing, except that mes- 
sages will start at the top of the screen. This bit is 
internal to NetView display management. 



..1. 



IFRAUPFW 



Indicates that a message is wide-line mode. This 
bit is internal to NetView display management. 



...1 



IFRAUSSI 



Indicates that a message was received on the ssi 
interface. This is to allow independent testing for 
wqe data from the indication that a message has 
been subject to system logging via wto. 
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Field 
Name 



Length 
or Mask 



Subfield 
orEQU 



Description 



IFRAUWAT 



1... 



Indicates that a message has satisfied a wait in a 
command list. This bit indication replaces 
changing hdrmtype to hdrtypwt, which obscured 
the hdrmtype value. dsiexi6 is driven with the 
message, and upon return NetView frees the 
buffer structures if all the display and log action 
indicators still say no-display, no-log, and sup- 
press override options. The driving of dsiexis for 
wait -suppressed messages is intended for 
accounting purposes, although resetting the indi- 
cators would allow logging of wait-suppressed 
messages, for example. 



IFRAUX16 



.1.. 



Indicates that dsiexi6 has been driven and pre- 
vents DSIEX16 from being driven again for this 
message. This bit is set to zero when received on 
a cross -domain session to allow processing in 
the new domain. 



IFRAUVSE 



.1, 



Indicates that the message is in vse format (Parti- 
tion id), (Reply id), (Message id). This bit is not 
reset when received cross -domain, allowing 
messages to retain their format integrity. 



IFRAUTA4 



1 byte 



The following six flags force the actions specified 
in ifrautai and ifrauta2 to be in effect regardless 
of the override command options specified for this 
task. If the bit is 1, the override is ignored. If the 
related ifrautai or ifrauta2 flags are B'OO', the 
action imposed by the defaults command or 
initial setting applies. The ifraufhd and ifraufbp 
when specified with non-zero values for the 
related ifrautai or ifrauta2 flags cause the beep or 
hold action to occur regardless of the initial set- 
tings or defaults command options. These flags 
may be set by NetView and are not reset when 
received cross domain so that dsiexo2a in the new 
domain can get a true picture of the original 
message. NetView sets ifraufsl, ifraufnl, and 
ifraufhl to prevent duplicate logging in multiple 
routed copies. When force flags are set before 
message automation occurs, either by NetView 
before dsiexo2a or by dsiexo2a, the automation 
table values for that option are ignored. 



1... 


IFRAUFHD 


Force hold actions 


.1.. 


IFRAUFSL 


Force syslog actions 


..1. 


IFRAUFNL 


Force netlog actions 


...1 


IFRAUFHL 


Force hardcopy actions 


1... 


IFRAUFDS 


Force display actions 


.1.. 


IFRAUFBP 


Force beep actions 
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IFR 



Field 
Name 



IFRAUCMB 



IFRAURTL 



IFRAUWF2 



Length 
or Mask 



Subfield 
orEQU 



Description 



4 bytes 



Points to a buffer with hdrmtype=hdrtypei and 
ifrcode=ifrcodcr used for command action. This 
buffer is built by the message table. Data buffers 
are sent on the ifrautba chain with the command. 



IFRAUPRS 


4 bytes 


Built and used only during message table proc- 
essing. 


IFRAUSRC 


16 bytes 


Provided for 16 bytes of user data. It is set to 
zeros when the aifr is created and is copied from 
the original buffer without change. 


IFRAUSOR 


8 bytes 


Used to retain the hdrsendr value when sending 
aifrs from one domain to another. 


IFRAUTAF 


8 bytes 


Used to retain the taf session name when 
replacing it with the domain id in aifr hdrdomid. 



4 bytes 



The address of the route action list only used 
during calls to dsiexi6. The routing list is mapped 
by the ifraurtb mapping. The ifrauaoi bit deter- 
mines whether the first or all active tasks in the 
list specified are sent the buffer. 



IFRAURSV 


20 bytes 


Reserved for expansion. It should not be used for 
any purpose. 


IFRAUWQD 


120 
bytes 


Maps the wqe data that has been processed into a 
format independent of levels of mvs and jes. 


IFRAUWHD 


4 bytes 


Eye catcher msg or dom. 


IFRAUWF1 


1 byte 


Flags 



1... 


IFRAUWFR 


mlwto first 


.1.. 


IFRAUWMD 


mlwto middle 


..1. 


IFRAUWLS 


mlwto last 


...1 


IFRAUWDO 


DOM 


1... 


IFRAUWSI 


Single message 


.1.. 


IFRAUWWR 


WTOR 


..1. 


IFRAUWSP 


Message suppressed 


...1 


IFRAUWBD 


Broadcast to all 



1 byte 



Flags 2 



1.. 


IFRAUWJN 


Display job names 


.1. 


IFRAUWST 


Display status 


.1. 


IFRAUWSS 


Display session 
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IFR 



Field Length Subfield Description 

Name or Mask or EQU 



IFRAUWF3 



1 byte 



Flags 3 



ifrauwta control line 



ifrauwtb Labe | |i ne 



ifrauwtc o ata | ine 



IFRAUWDF 



.1 ifrauwtd End line 



IFRAUWF4 


1 byte 


Flags 4 


1 . . . IFRAUWDT D0M by ASID and TCB 


.1.. IFRAUWDA DOM by ASID 


IFRAUMCS 


2 bytes 


mcs flags 


IFRAUWMA 


1 byte 


Area id 


IFRAUWDS 


2 bytes 


Descriptor codes 


IFRAUWAS 


2 bytes 


asid of issuer 


IFRAUWJT 


4 bytes 


jstcb of issuer 


IFRAUWWI 


4 bytes 


smsgid value 


IFRAUWUC 


4 bytes 


Target console ucmid 


IFRAUWSN 


8 bytes 


System name 


IFRAUWRT 


16 bytes 


Route codes 


IFRAUWTL 


4 bytes 


Text length 


IFRAUWJU 


8 bytes 


Job number 


IFRAUWJA 


8 bytes 


Job name 



1 byte 



Message format 



Note: The aifr is fixed length at 256 bytes including the bufhdr and hdrmcext. Do 
not expand it. 



Automation Internal Function Request Routing List 



ifraurtb is the mapping of the route action list that is used during dsiexib proc- 
essing, ifraurtl is the address of a standard NetView buffer with a standard buffer 
header and a standard buffer header extension. The route list within this buffer 
contains a list of names who get identical copies of the ifrcodai structure. Bit 
ifrauaoi determines whether all active or the first active name receives a copy of 
the ifrcodai. hdrmsg is a field within bufhdr that is part of the dsitib control block 
macro. This buffer must be addressed separately from the ifrcodai buffer. 
hdrbleng, hdrmleng, and hdrtdisp are the only fields that must be initialized in this 
buffer header. 
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IFR 



Usage Notes 



Field Name Length Description 



ifraurcc 2 A halfword count of the number of route names that follow. The 

bytes hdrbleng value must be sufficient to contain this number of 
names plus the buffer headers. 

ifraurcl -jo A variable size array of 10-character names. These must 

bytes contain an operator id of no more than 8 characters padded 
with blanks to a length of 10. 



Multiple 10 character fields continue here. 



Setting the message action flags in the buffer in dsiexo2A is equivalent to specifying 
the options in the message automation table. If the message is selected by the 
message automation table, any options specified by the table overlay the dsiexo2a 
values. The message is then evaluated after dsiexo2A and table processing against 
criteria specified by defaults and override commands to determine display and 
logging actions, ifrauact must be set to 1 if any actions are selected by dsiexo2A. 

In the bufhdr that precedes the ifr: 

1. hdrmtype is specified as t* (hdrmtype =x'C9'; symbol hdrtypei). Because an ifr 
is transferred by dsimqs, the ifr contains a message command extension when 
it is received. The extension is optional in some cases but is recommended for 
consistency. If a command processor receives control with a command buffer 
and hdrmtype = hdrtypei, it is assumed that there is a command extension and 
an ifr. 

2. hdrtdisp contains the displacement to the ifrcode. For ifrcodcr and ifrcodus, 
NetView modifies hdrtdisp and hdrmleng so that all commands appear the 
same to the command processor. The command verb is followed by the 
parameters. The ifr section is logically removed. 
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LOGDS 



LOGDS - NetView Log DSECT 



The NetView log dsect maps the record written to the network log. 
The relevant fields in the logds are as follows: 



Field Name 


Length 


Description 


LOGDATE 


4 


Date of record; format is 0OYYDDDC. 


LOGDISP 


2 


Record text displacement. 


LOGDOMID 


8 


Domain id of record originator. 


LOGKEYDT 


4 


Same as logdate. 


LOGKEYTM 


4 


Time of record; format is HHMMSSOC, where HH is the hour, MM is 
the minute, SS is the second, and OC is the symbol for packed 
decimal. 


LOGLUNAM 


8 


Task name of record originator. 


LOGMTYPE 


1 


Message type of record. 


LOGOPID 


8 


Operator id of record originator. 


LOGSEQ# 


4 


Sequence number for vsam key. 


LOGTEXT 




Text of Network log record. 



LOGTIME 



Same as logkeytm. 



Chapter 7. Control Block Reference 141 



MVT 



MVT — Main Vector Table 



The main vector table (mvt) is the main control block for information throughout 
NetView. It contains global information, such as the domain name, the status of 
NetView, and pointers to other tables and subtasks. 

There is one mvt for each NetView. You can locate the mvt from a subtask through 
theTVBMVT, a pointer in the task vector block (tvb). A using statement for the dsect 
for the mvt must precede most macro invocations. 

The relevant fields in the mvt are as follows: 



Field Name 


Length 


Description 


MVTARTLN 


2 


Length of each entry in dsiart. 


MVTCBH 


4 


A standard control block header. 



MVTCDSES 



MVTCLOSE 



MVTCURAP 



MVTDRTRY 



MVTGFMG2 



MVTGMSG 



MVTMETH 



The number of osts in other domains that may have sessions at 
one time with this NetView. This is the number of tvbs created 
for nnts in the tvb chain. This number is specified in the 
cdmnsess definition statement. 

A flag bit that indicates that the close normal command has 
been issued. When the bit is on, no more subtasks are attached 
and logons are not accepted. 



9 The value from the nccfid definition statement domainid param- 

eter, as follows: 

mvtcural 1-byte field that shows the length of the nccfid 
domainid (one to five characters). 

mvtcuran 8-byte field that contains the nccfid domainid padded 
with blanks. 

mvtdprad a 



4 Address of NetView subtask dispatcher (for compatibility with 

NetView Release 2 vse only). 

2 The number of times an i/o operation is retried before it 

becomes a permanent error. 

mvtgfmgi 4 a pointer to a Write-to-Operator parameter list containing the 

message, osn24i storage request failed for nccf. This message 
may be used by any wto macro with mf=e. No additional 
storage is required. The routing code is (2,11); the descriptor 
code is 11. 



A pointer to a Write-to-Operator parameter list containing the 
message, DS11251 critical storage shortage for nccf. This 
message may be used by any wto macro with mf=e. No addi- 
tional storage is required. The routing code is (2,11); the 
descriptor code is 11. 

Pointer to a buffer containing the message, dsio73A command 
processor unable to build response message. 

Indicates that the access method is vtam (v). 



mvtmlgon 



mvtmrc 



The number of times invalid logon information is processed 
before that terminal session ends. This number is specified in 
the maxlogon definition statement. 

The number of times an ost or ppt may abend and be rein- 
stated. This number is specified in the maxabend definition 
statement. 
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MVT 



Field Name 


Length 


Description 


MVTNCCFQ 


8 


The qname value for macros enq and deq. 


MVTSNT 


4 


Address of span Name Table. 


MVTSNTLN 


2 


Length of each entry in dsisnt 


MVTSVL 


4 


The address of the service routine vector list (svl) that contains 
the addresses of the service routines. 


MVTTOD 


8 


The system time-of-day clock when NetView was started. 


MVTTVB 


4 


The address of the first tvb in the tvb chain. 


MVTTVBRN 


18 


The rname value for the tvb chain. 


MVTUFLD 


4 


A user-defined field. 



mvtver 



Contains a displayable identifier for the release of NetView 
under which your code is running. 
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MVT 



MVT DSIEX16 Interface Data 

For field name mvtaidft, the following defaults are set in dsimvt and relate to 

DSIEX16. 



Length or Start-up Description 

Mask Value 



1 byte 




Contains message process defaults. 


1 


1 


1 = Messages are allowed to be held on the screen. 
- Messages are not allowed to be held on the screen. 


.x 




Reserved 


..Q 





= Messages other than NetView wto and wtor are not written 
to the system log. 

1 = NetView messages are written to the system log. 


...1 .... 


1 


1 = Messages are written to the NetView log if the NetView log 

is active. 

= Messages are not written to the NetView log. 


.... 1... 


1 


1 = Messages can be written to the hardcopy log if one is 

started for the operator. 

= Messages are not written to the hardcopy log. 



. . . .1. . 1 1 = Messages can be displayed on the NetView operator's 

station. 

= Messages can not be displayed on the NetView operator's 
station. 

1. 1 1 = Messages may beep on the NetView operator's station. 

= Messages can not beep on the operator's station. 



x 



Reserved 



Notes: 

1. These settings are changed by using the defaults command. 

2. The interpretation of the results of the settings is affected by the settings of aifr 
flags for a message and by the override command settings currently in effect 
for each operator. 

3. Some messages are not affected by any or all of the above. 
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OIT 



OIT — Operator ID Table 



The operator id table (oit) is a mapping consisting of multiple entries. Each entry 
includes the name of the NetView operator id and indicators relative to that oper- 
ator id. This table is used by the dsiois macro. 

The mapping of the operator id table is as follows: 



Field Name 


Length 


Description 


OITCBH 


4 


Control block header. 


OITTABLE 


* 


Multiple entries. 


OITENTRY 




Format of each dsioit entry. 


OITID 


8 


Operator ID. 



0ITIND 2 Indicator flags 

X'80' - operator is logged on to this NetView. 
X'40' - operator is in session with this NetView. 
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PDB 



PDB — Parse Descriptor Block 



The parse descriptor block (pdb) contains parse information for a command pointed 
to by cwbbuf in the cwb or by userpdb in the use. The pdb has no fixed length. The 
relevant fields in the pdb are as follows: 



Field Name 


Length 


Description 


POBCBH 


4 


Standard control block header. 


PDBBUFA 


4 


The address of the command buffer, cwbbuf also contains this 
address. 



PDBCMDA 



PDBFLAGS 



PDBTABLE 



A pointer to the entry in the system command table (sct) for the 
verb in the buffer that caused this command processor to be 
called. Macro dsipas (parameter alias services) and dsikvs 
(keyclass and valclass lookup services) use this entry as a 
parameter. 



1 Indicator byte for command processors. 

pdbimmed 1 = runs as an immediate command, 

— runs as a regular command or a data services 
command. 

pdbnoent 2 The number of syntactical element entries in the pdb, including 

the verb and all parameters. 



Label to indicate the beginning of pdb entries. 



pdbentry 



Each syntactical element creates one entry in this portion of the 
pdb. The verb is always the first entry. Each entry contains the 
length, the delimiter, and the offset from the beginning of the 
buffer, as specified in the following three fields: 



pdboisp 



pdbleng 



pdbtype 



pdbentnd 



A 2-byte field specifying the offset from the start of 
the buffer to the first character of the nth syntactical 
element. For example, element addr(n) = pdbbufa 

4- PDBDISP(n). 

A 1-byte field specifying the length of the particular 
syntactical element. This field does not include the 
length of the delimiter. When two delimiters other 
than blanks occur sequentially, the length is zero. 
Also, when two delimiters are separated by a blank 
or blanks, the value of the length is zero. The offset 
is set to point to the second delimiter. 

A 1-byte field containing the delimiter character that 
separates this element from the next one. The 
standard parsing delimiters are blank, comma, 
period, and equal sign. The end of the record is 
treated as if it were delimited by a blank. Multiple 
blanks are treated as one blank. Blanks preceding 
a syntactical element are ignored. For example, 

verb parameter1,parameter2" 
creates the following: 

1. An entry for the verb (preceding blanks are 
ignored) 

2. An entry for parameterl , delimited by a comma 

3. An entry for parameter2, delimited by a blank. 

A label at the end of pdbentry for use in computing 
the length of pdbentry. 
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SCE 



SCE — System Command Entry 



The system command entry (sce) contains information about a command. Macro 
dsices returns the sce of a verb or command processor. The address of the sce is 
also input to macro dsipas. 

The relevant fields in the sce are as follows: 

Field Name Length Description 

scecaddr 4 p or mvs/xa, this is the address of the linkage assist routine for 

command processors, dsicmdld. For operating systems other 
than mvs/xa, this is the address of the command processor's 
entry point. 

scelname 3 y ne | oao - module or phase name of the command processor to 

be called for the verb. 

scercadr 4 jhe address of the command processor's entry point for mvs/xa. 

For operating systems other than mvs/xa, this field has no 
meaning. 

sceverb g The command verb, left-justified and padded with blanks. 
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SCT 



SCT — System Command Table 



The system command table (sct) contains a system command entry (sce) for each 
command defined to NetView in the cmdmdl definition statement. There are no 
user fields here; however, you must include this control block mapping to get a 
mapping of the sce. 
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SNT 



SNT — Span Name Table 



The span name table (snt) is a mapping consisting of multiple entries. Each entry 
includes the name of the span of definition and indicators to define those operators 
that may be controlling the span. This table is used by the dsisss macro. 

The mapping of the span name table is as follows: 



Field Name 


Length 


Description 


SNTCBH 


4 


Control block header. 


SNTTABLE 


* 


Multiple entries. 


SNTENTRY 




Format of each dsisnt entry. 


SNTNAME 


8 


Span name. 



sntopdef * Variable length bit string, where each bit corresponds to a rela- 

tive entry in the Operator id table. If a bit is on (1), the corre- 
sponding operator may control this span. 
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SVL 



SVL — Service Routine Vector List 



The service routine vector list (svl) is used by NetView macros to call the 
requested service routine. The svl contains the addresses of all service routines, 
except for presentation service routines. There are no user fields here; however, 
you must include this control block mapping to use NetView services. 
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SWB 



SWB - Service Work Block 



The service work block (swb) contains the parameter list for most service facilities 
used in user-written code. 

The relevant fields in swb are as follows: 



Field Name 


Length 


Description 


SWBADATD 


256 


Automatic work area to be used for reentrant variable defi- 
nition. 


SWBLRCPL 


* 


Mapping dsect for area where caller builds parameter lists for 
dsipush, Dsipop.and dsifind. 


SWBPLIST 


256 


Parameter list area. 


SWBSAVEA 


72 


A standard save area. 


SWBTIB 


4 


Pointer to the caller's tib. 



MQSENTTO 



Operator id of the operator to whom the message was sent. 
Returned to the issuer if dsimqs is issued with a list of type 1st 



For a description of swblrcpl fields, see"DSIPUSH - Establish Long Running 
Command" on page 202, "DSIPOP - Remove Long Running Command" on 
page 190, and "DSIFIND — Find Long Running Command Storage" on page 169. 
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TIB — Task Information Block 



The task information block (tib) keeps information about an attached subtask. tib is 
acquired and freed by the main task. 

The tib fields described below apply to optional subtasks: 



Field Name 


Length 


Description 


TIBCBH 


4 


A standard control block header. The cbhtype field contains the 
same information as the cbhtype field in the tvb. 


TIBACB 


4 


A pointer to a vtam acb for NetView subtasks. This field may be 
defined by the subtask. 


TIBAPID 


9 


The vtam application program name for a NetView subtask. 
This field may be defined by the subtask. 


TIBAPWD 


9 


The vtam password for NetView subtasks. This field may be 
defined by the subtask. 


TIBAREA1 


62 


Pointers to other control blocks such as cwb, swb, or pdb for 
NetView subtasks. This field may be defined by the subtask. 



TIBCLRDF 



Default color. 

X'OO 1 Color field not found. 
X'F4' Green 
X'FA' Orange 



TIBCLR# 


1 


Number of colors supported. = default, 4 = base color, and 
7 = extended color. 


TIBEDATD 


256 


A scratch area for subtask use. 


TIBECBPO 


1 


A one-byte constant to test whether an ecb has been posted. 


TIBELT 


4 


A pointer to the subtask ecb list. 


TIBEXLST 


4 


A pointer to the vtam exlst for NetView subtasks. This field may 
be defined by the subtask. 



TIBFLGS 1 A byte of flags. 

tiblrcnp = 1 means the resume routine has been newly pro- 
moted and should put out a new screen. 

TIBHLlTE 1 Highlight support flags. 

tibblink = 1 means blinking is supported. 
tibrevrs = 1 means reverse video is supported. 
tibunscr = 1 means underscore is supported. 



TIBMSGNM 


8 


The operator identifier of the subtask that issued the start task 
command. If the subtask was started automatically with init=y, 
this field contains zeros. 


TIBMUXIT 


1 


A counter used to track the level of multiple asynchronous 
interrupts. 


TIBNDATD 


256 


A scratch area for subtask use. 


TIBOSEXT 


4 


A pointer to an optional subtask extension to the tib. The 
optional subtask releases any storage pointed to by this area. 


TIBOSLST 


4 


The command processor list uses this field to display the 
status of an optional subtask. 


TIBSAVEE 


72 


A save area for subtask use. 



TIBSAVES 



72 



A save area for subtask use. 
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TIB 



Field Name 



Length Description 



TIBSCRID 



Screen identifier. 

tibscrm 1-byie screen modification type. 
tibscrsn 3-byte screen serialization number. 



TIBTVB 



TIBUFLD 



TIBXECB 



A pointer to the tvb. The address of the mvt can be obtained 
from the tvb. mvt locates all other control blocks. 

This field is not referenced or changed by NetView. It may be 
defined by the subtask. 

NetView uses this field as an ecb for cross-domain communi- 
cation in ost and nnt. It may be defined by the subtask. 
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TVB 



TVB — Task Vector Block 



The task vector block (tvb) contains information about the status of the subtask. 
There is one tvb for each subtask in NetView. Certain service routines, such as 
dsipss, use the tvb to store control information that is important for processing their 
code. 

The tvb contains pointers to the mvt and the tib. You can obtain the addresses of 
other important control blocks from these control blocks. The tib, an extension of 
the tvb, represents an active task, tvbs are chained together through the tvbnext 
field. The beginning of the chain is pointed to by mvttvb. 

The relevant fields in the tvb are as follows: 



Field Name 



Length Description 



TVBCBH 



TVBNEXT 



A standard control block header. The cbhtype byte indicates 
the subtask type: 



X'OO' 


PPT 


x'or 


NNT 


X'02* 


OST 


X'03' 


HCT 


X'05" 


Optional subtask, 



To distinguish between different types of optional subtasks, 
refer to the field tvbmodnm. 



TVBMECB 


4 


An event control block (ecb) that notifies the subtask that a 
message or a queue of messages has been sent using macro 

DSIMQS. 


TVBMECBH 


4 


An event control block (ecb) that notifies the subtask that a high- 
priority message or queue of messages has been queued to the 
high-priority public message queue (TVbmpubh). 


TVBMECBL 


4 


An event control block (ecb) that notifies the subtask that a low- 
priority message or queue of messages has been queued to the 
low-priority public message queue (tvbmpubl). 


TVBMPRIQ 


4 


The address of the normal-priority private message queue. 


TVBMPRQH 


4 


The address of the high-priority private message queue. 


TVBMPRQL 


4 


The address of the low-priority private message queue. 


TVBMPUBH 


4 


The address of the high-priority public message queue. See 
"Intertask Communication" on page 82 for information on proc- 
essing public and private message queues. 


TVBMPUBL 


4 


The address of the low-priority public message queue. See 
"Intertask Communication" on page 82 for information on proc- 
essing public and private message queues. 


TVBMPUBQ 


4 


The address of the normal-priority public message queue. See 
"Intertask Communication" on page 82 for information on proc- 
essing public and private message queues. 


TVBMVT 


4 


A pointer to the mvt. 



A pointer to the next tvb on the tvb chain. The tvb chain is 
anchored from mvttvb. 
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TVB 



Field Name 



Length Description 



TVBPRIQ 



1 



Priority queuing flags. 
tvbmm = 1 



The subtask provides services for the high- 
priority and low-priority message queues as well 
as the normal queue. 



TVBRESTE 



TVBTCB 



An event control block (ECB) that notifies the subtask that reset 
command has been entered. 

The mvs task control block (tcb) address. 



TVBTECB 



TVBTIB 



An event control block (ecb) that requests that the subtask shut 
down as soon as possible. Include tvbecb in every subtask ecb 
list. A subtask may use this ecb to cause itself to shut down. 

A pointer to the tib for the subtask. 



The subtask uses the following bit fields. Some of these flag bits are defined by the 
subtask; others are defined by the main task. 



Field Name 



Length Description 



TVBAIIFR 



tvbhcuse 



TVBIND1 



4 Address of message buffer structure when command is driven 

from the message automation table. Otherwise, 0. 

4 May be defined by the subtask. For an hct, this field tracks the 

number of subtasks currently using the hard-copy subtask. 

1 Indicator byte. 

tvbterm A value of 1 indicates that the subtask has ended 

normally, and the subtask has released all 
resources. This bit must be supported by the 
subtask. If the bit is set on by the main task 
before attaching the subtask, a value of 1 indi- 
cates to the subtask that it has been attached for 
cleanup. The subtask is to release all resources 
and return control to the main task with this bit 
still set to 1. 

TVBIND2 1 



Indicator byte. 

TVBVCLOS 
TVBABLOG 



This flag bit may be defined by the subtask. 
A 1 indicates a task is being re-initialized just 
after an abend. 



TVBIND3 



1 Indicator byte. 

tvbactv = 1 The subtask is active. This bit is set by the 

subtask. While this bit is on, messages may be 
sent to the subtask using macro dsimqs. 

tvbinxit = 1 An irb exit routine is running. 

tvblgoff = 1 The subtask is ending upon request. 

tvblgon = 1 The subtask is starting. 

tvbrcvai May be defined by the subtask. For an ost or an 

nnt, tvbrcvai = 1 means a receive any for cross- 
domain sessions has been issued. 

tvbreset = 1 Regular commands should stop processing 
immediately. If your subtask does not run 
command processors, you may redefine this 
flag. 

TVBIND4 1 



Indicator byte. 

tvbrcvry 1 means recovery is in progress for this subtask. 
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TVB 



Field Name 



Length Description 



TVBLUNAM 



TVBMEMNM 



TVBMODNM 



TVBOPID 



TVBUFLD 



TVBZIND2 



8 The value specified in the tskid parameter of the task definition 

statement. This field is initialized before the subtask is 
attached. 

8 This field is initialized with the mem parameter of the task defi- 

nition statement of dsidmn. It may be the name of the member 
of the data set dsiparm (for mvs) or a file with filetype nccflst 
(for vm) that contains the initialization parameters for an 
optional subtask. 

8 The name of the module to be attached as a subtask as speci- 

fied in the mod parameter of the task definition statement. This 
field may be used to determine the type of optional subtask. 

8 The unique subtask identifier. This name may be the same as 

tvblunam. It is set up by the subtask when initialization is com- 
plete. 

4 A user field that may be defined by the subtask. 



Indicator byte. 
tvbabend 

tvblogof 
tvbresum 



The abend reinstate routine is running. If this 
indicator is on, macros dsipush and dsipop cannot 
be issued. 

The logoff routine is running. If this indicator is 
on, dsipush and dsipop cannot be issued. 

The resume routine is running. 



TVBZIND4 



Indicator byte. 

TVBAUTOO 
TVBAUTVE 
TVBAUTVS 



User code is running under an unattended oper- 
ator task. 

The task depends on vtam and must be termi- 
nated by the main task when vtam ends. 

The task depends on vtam and must be reat- 
tached by the main task when vtam starts. When 
vtam ends, the task terminates. 
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USE — User Exit Parameter List 



The user exit parameter list (use) contains addresses for the following: 

• The buffer containing the message 

• The lu name associated with the message 

• The operator identification 

• The service work block (swb) 

• The task vector block (tvb) 

• The parse descriptor block (pdb). 

An extension of use is present for dsiexi2 and the dst exit routines involved with 
input and output (xrrco, xitci, xitvn, xitvi, xitvo, xitxl). For DSIEX12, the password, 
hard-copy printer name, and profile name are given. For the dst exit routines, the 
address of dsrb is given. 

The relevant fields in the use are as follows: 



Field Name 



Length Description 



USERCBH 



USERLGON 



4 A standard control block header. The second byte, usercode, 

indicates the exit routine that is called. Values X'01 1 - X'10 1 
correspond to user exits dsiexoi - dsiexi6. The dst user exit 
codes are defined in the use control block. 

36 An extension for dsiexi2 and the dst exit routines. If present, 

this extension contains the following fields: 

usedsrb 4 For dst exit routines, the fields xitvi, xitvo, xitci, 
xitco, and xitxl point to the dsrb associated with 
the dst i/o request. For other exit routines, this 
field is not initialized. 

usenpswd 8 For dsiexi2 only, this field contains the new pass- 
word successfully entered by the operator at 
logon when options verify= maximum. If options 
verify = minimal or options verify = normal is spec- 
ified, usenpswd contains blanks (X'40 1 ). For exit 
routines other than dsiexi2, this field is not initial- 
ized. 

userhcpy 8 For dsiexi2 only, this field contains the name of 
the hard-copy printer used by the operator for 
this session. If no hard copy is used or if options 
verify = minimal is specified, userhcpy contains 
blanks (X'40 1 ). For exit routines other than 
dsiexi2, this field is not initialized. 

userprof 8 For dsiexi2 only, this field contains the name of 
the profile used for this session. If options 
verify = minimal is specified, userprof contains 
blanks (X'40 1 ). For exit routines other than 
dsiexi2, this field is not initialized. 

userpswd 8 For dsiexi2 only, this field contains the operator 
password entered at logon. If options 
verify = minimal is specified, userswb contains 
blanks (X'40 1 ). For exit routines other than 
dsiex-12, this field is not initialized. 
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Field Name 



Length Description 



USERLU 



USERSWB 



USERTVB 



A pointer to an 8-byte area that contains the logical unit name 
(luname) related to the subtask in control, as follows: 



Task 

MNT 
OST 
NNT 



PPT 



HCT 
DST 



Name 

The characters 'sysop'. 
The node name of the operator's terminal. 
The appl name of the ost that issued the start 
domain command (nccfid domainid followed by a 
3-digit number). 

The nccfid domainid parameter followed by the char- 
acters 'ppt'. 

The node name of the hard copy-printer. 
The name from the tskid parameter of the task defi- 
nition statement. 



usermsg 4 /^ p j n ter to a buffer in standard buffer format, consisting of a 

buffer header (bufhdr) followed by text. For input-type exits, 
device dependencies have been removed. In exit routines 
dsiexi4, xitdi for end-of-file, and xitvn, this field is set to 0. 

In dsiexo4, the buffer is in the format set up by the caller. It has 
not yet been reformatted for the network log, mvs system log, or 
hard-copy log. 

useropid 4 ^ pointer to an 8-byte area that contains a name related to the 

subtask in control, as follows: 

Task Name 

MNT The characters ' sysop ' . 

OST The operator identifier. 

NNT The operator identifier. 

PPT The nccfid domainid parameter followed by the char- 

acters 'ppt'. 

HCT The node name of the hard copy-printer. 

userpdb 4 a field that points to a pdb or contains 0. The pdb contains 

parse data that relates to the buffer to which usermsg points. 
For exit routines dsiexo2, dsiexo4, dsiexo7, dsiexo9, dsiexio, dsiexu, 
xitxl, and xitdi for end-of-file, this field contains 0. A pdb is not 
available when calling these exit routines. 



A pointer to the swb, which the exit routine uses as a work area 
or uses to request services from NetView. If necessary, 
another swb may be obtained using macro dsilcs. 

A pointer to the tvb. The tvb contains information about the 
subtask under which the exit routine was called. The tvb 
obtains the addresses of the tib, the mvt, and the svl (through 
the mvt). 
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Chapter 8. Macro Reference 



This chapter describes the purpose and coding of the NetView program macros. 
You may use these macros to request various service facilities when writing your 
own user exit routines, command processors, and subtasks. You must be in 
problem program state and user protection key for all these macros. NetView 
macros overwrite registers 0, 1, 14, and 15. 

Prior to issuing any macro except dsicbs, you must set register 13 to a standard 
72-byte save area. 

All return codes in this chapter are shown in decimal. 

Use only the parameters documented in this book. Any undocumented parameters 
that a macro may have are only for internal use by the NetView program and must 
not be used in user-written programs. Macro expansions are not part of the 
intended interface. 



Notational Conventions 

The following notational conventions apply to the macros described in this chapter. 

UPPERCASE item 

Uppercase letters represent parameters that you must code as shown. 

lowercase item 

Lowercase letters represent parameters for which you must supply the 
value, address, or name, rather than the literal information. 

underscored item 

An underscored item represents the default value of a particular param- 
eter. If you specify no parameter, NetView uses the default value. 

Braces { } 

Small braces enclose the different options for a parameter. Large 
braces enclose mutually exclusive parameters; you must select one, 
and only one, of these parameters. Do not include the braces when 
coding the information. 

Brackets [ ] 

Brackets enclose an optional parameter. Optional parameters can be 
included or omitted independently of other parameters. Do not include 
the brackets when coding the information. 



OR-sign | 



The OR-sign separates the options for a required (brace-enclosed) 
parameter or for an optional (bracket-enclosed) parameter. For a 
required parameter, one of the options must be coded. For an optional 
parameter, none of the options have to be coded. Do not type the 
OR-sign when coding the information. 
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DSICBS - Control Block Services 



Macro dsicbs includes dsects for the control blocks required for user-written pro- 
grams during assembly. 

dsicbs ensures that a control block is included only once, inner control blocks are 
included if necessary, and each definition for an inner control block precedes the 
definition of the outer control block, dsicbs also controls the format and printing, or 
suppression, of dsects for the control blocks. 

mvt addressability is not required. 



[name] DSICBS [cbname,...] 

[.EJECT = (YESlNOn 

[.DEFER = {ALL|THESE|INCLUDE|NO}] 

[,PRINT={YES|NO}J 



cbname 

Name of a control block, starting with dsi, to be included. Names must be sep- 
arated by commas. 

EJECT 

Specifies that eject statements are performed between each control block 
expansion and after the last expansion. 

DEFER 

Defers control block expansions. 

ALL 

Specifies that all subsequent dsicbss are not expanded until a dsicbs 
defer = include is encountered. (If you specify this parameter, be sure to 
code dsicbs defer= include later in the program.) 

THESE 

Specifies that these control block expansions are delayed until a dsicbs 
defer= include is encountered. 

INCLUDE 

Specifies that any deferred control block expansions are to be expanded at 
this point in the program. 

NO 

Specifies that the control blocks are to be expanded immediately. 

PRINT 

Specifies that control blocks will be printed (expanded) in the assembler 
listing. 
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DSICES - Command Entry Services 



Macro dsices uses a specified buffer, parse descriptor block (pdb), or load module 
name to locate a command processor address. 

dsices locates a system command entry (sce) that corresponds to the command 
verb and returns the sce's address to a user-provided fullword area. 

mvt addressability is required. 



[name] DSICES SWB = {{register)\symbolic name} 
' ,BFR = {{register)\symbolic name}\] 
< ,PDB = {(register)\symbolic name}| | 
. .MODNAME = modulename J 

.SCTADDR = {(register)\symbolic name} 
[,CLISTCK = {YES|NO}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). swbtib identifies your tib, which identifies your task 
type. 

Note: bfr, pdb, and modname are mutually exclusive, and one of the three must be 
specified. 

BFR 

Register, or symbolic name of a fullword area, containing the address of the 
buffer that contains the verb to be analyzed. This buffer must have an initial- 
ized bufhdr. 

PDB 

Register, or symbolic name of a fullword area, containing the address of a 
completed parse descriptor block (pdb) to be used as input. 

MODNAME 

Specifies the module name to be located in the system command table. The 
modulename may be specified as the field that contains the module name or 
as the module name enclosed in single quotes. 

Note: The first entry that is found in the sct corresponding to the module 
name will be returned. If the module name specified is defined in dsicmd on 
more than one cmdmdl statement, then an unexpected address may be 
returned. In this situation, the bfr operand should be used instead. 

SCTADDR 

Register containing the address of a user-provided fullword area, or the sym- 
bolic name of that area, where the address of the system command entry cor- 
responding to the module name or verb is to be returned. The returned pointer 
addresses an sct entry (SCE) dsect. 

CLISTCK 

Specifies whether to check for a valid command list name if the command has 
no cmdmdl statement in dsicmd. 

Note: clistck cannot be specified with modname. 
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Return Codes in Register 15 

Function was successful. One of the following occurred: 

1. A regular command was found in the system command table and the 
address of the sct entry was returned. 

2. The verb was not found in the sct (if clistck was specified, a command 
list was found with the specified name), and the dummy sct entry for a 
command list was returned. 

4 The command found can be processed as a regular or immediate command; 
the address was returned. 

8 An immediate command was found in the system command table; the 
address was returned. 

12 The module was not found, or there was an invalid verb length; no address 
was returned. 

16 Scope class failure. Either the operator was not authorized to issue the 
command, or storage could not be obtained to check the scope class. No 
address was returned. 

20 Either the command found was incompatible with the task type that called the 
routine, and the address is returned, or clistck=yes was specified and the 
request was issued in an asynchronous exit, and the address is not returned. 

24 clistck=yes was specified, but the command or command list was not found 
in dsisct or DSICLD. 

28 clistck = yes was specified, but storage requested for clistck processing 
could not be obtained. 
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DSIDATIM - Date and Time 

Macro dsidatim obtains and formats the time and date. 

dsidatim places the time and date in an output area. This macro can be used to 
obtain the time for the hdrtstmp field of a message. 

mvt addressability is required. 



[name] DSIDATIM AREA = {{register)\symbolic name} 
[.FORMAT = {EBCDIC | BINARY}] 



AREA 

Register containing the address of the area into which the date and time are 
returned, or symbolic name of that area. This area does not have a buffer 
header. 

FORMAT 

Specifies the format of the output. 

EBCDIC 

Returns the date and time in 17 bytes, formatted as follows: 

mm/dd/yy hh:mm:ss 

mm is the month, dd is the day, yy is the year, hh is the hours mm is the 
minute, and ss is the second. 

BINARY 

Returns the date and time in 8 bytes in packed decimal format as follows: 

X'OGyydddFhhmmssOC 

yy is the year and ddd is the Julian date, hh is hours, mm is minutes, and 
ss is seconds. The inital X'00\ the middle XT', and the ending X'OC are 
characters which indicate the data is packed decimal. 

Usage note: When using the binary form of dsidatim to initialize a hdrtstmp, use 
an 8 byte work area for the area, and move the low order 4 bytes to hdrtstmp. 
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DSIDEL - Delete User-Defined Module 



Macro dsidel deletes user-defined load modules. You specify the name of the 
module to be deleted. 

mvt addressability is not required. 



[name] DSIDEL f EP = modulename 



\ EPLOC= {(reg/ster) | symbolic name} J 
[,DPR = {(reg/sfer)|MVTDPRAD( I MVTPTR)}3 



EP 

Specifies the name of the module to be deleted. 

EPLOC 

Specifies the address of an 8-byte field that contains the module name to be 
deleted. The module name should be left-justified and padded with blanks. 

DPR (required for NetView Release 2 vse only) 

In vm/sp and mvs, this parameter is ignored. However, if you want to write a 
routine to compile and run on both a NetView Release 2 vse system and on a 
NetView Release 3 mvs or vm/sp system, you will need to include this param- 
eter. In vse, this parameter specifies a register containing the address of the 
NetView dispatcher (dsidprnv), or mvtdprad(,mvtptr), where mvtptr is the sym- 
bolic name of a fullword area that contains the address of the mvt. 



Return Codes in Register 15 

Zero Module has been deleted. 



Nonzero Attempt to delete module was unsuccessful. For more information, 

refer to OS/VS Supervisor Services and Macro Instructions or CMS 
Commands and Macro Reference. 
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DSIDKS - Disk Services 



Macro dsidks can be used to connect to a ddname, locate a member, and read the 
records in that member. This macro can only be used to connect to data sets with 
the following ddnames: dsicld, dsiparm, dsiprf, dsivtam, dsimsg, cnmpnli, bnjpnli, 
bnjpnl2, or bnjmisc. (NetView opens these data sets, and keeps them open as long 
as it is up.) You can then use dsidks to find and read any member in any of the 
data sets concatenated under any of these ddnames in your NetView startup proce- 
dure. 

You must have a copy of the dsect for the disk service block (dsb) included in your 
program, mvt addressability is required. 



[name] DSIDKS SWB = {{register)\symbolic name} 

.DSBWORD = {{register)\symbolic name} 
,TYPE= {CONN|FIND|DISC} ,NAME = {(regf/ster)h 

symbolic name} I 

.TYPE = READ J 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

DSBWORD 

Register containing the address of a user-provided fullword area on a fullword 
boundary, or symbolic name of that fullword area. When the macro completes 
processing for type = conn, this area contains the address of the disk service 
block (dsb). For other disk service requests, this area must specify the dsb 
address previously obtained by type=conn. 

TYPE 

Specifies the type of processing the service routine is to perform. 

CONN 

Specifies that the service routine is to connect to or access the caller's 
definition name (ddname). The address of the disk service block (dsb) is 
returned in the area specified by the dsbword parameter, dsidks must be 
issued with this option before any other options may be chosen. 

FIND 

Specifies that the service routine is to find the member specified by the 
name parameter. If the member is found, the first record is read, dsbbuff 
addresses the buffer containing this record. Do not specify this option 
unless the conn option has been specified. 

DISC 

Specifies that the service routine is to disconnect from the ddname and 
release the dsb. 

READ 

Specifies that the service routine is to read the next sequential record in 
the member. Do not specify this option unless the find option has been 
specified. 



Chapter 8. Macro Reference 167 



DSIDKS 



NAME 

For type=conn and type=disc, a register containing the address of an eight- 
character user area with the caller's definition name (ddname), or the symbolic 
name of that area. The area should be left-justified and padded with blanks. 

For type = find, name is a register containing the address of an eight-character 
user area that contains the name of the member to be read, or the symbolic 
name of that area. 



Return Codes in Register 15 

For type = conn: 



Function was successful. Data control blocks and i/o buffer were gotten and 
initialized. 

4 Invalid data set name (for mvs) or filetype (for vm) was specified. 

12 No storage was available for i/o buffer. 

For type - find: 

Function was successful. Member or file was found and the first record was 
read. 

4 Member or file was not found in the source statement library or in the speci- 
fied library, or an empty member or file was found. 

8 Member or file was found but an i/o error occurred on the first read. 

12 Specified definition name or data set has not been opened. 

20 Specified control block identifier was invalid; the member or file was not 
found. 

For type = disc: 

Disconnect was successful; data and i/o buffer were freed successfully. 

4 Invalid filetype was specified, (vm only) 

8 Disconnect failed, (vm only) 

20 Specified control block identifier was invalid and no storage was freed. 

For type = read: 

Function was successful; record was read. 

4 End of data was reached. 

8 i/o error occurred during reading. 

12 Reading this record is prohibited; an i/o error may have occurred, end of data 
may have been reached, or the caller did not issue type= find first. 

20 Specified control block identifier was invalid; the record could not be read. 
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DSIFIND - Find Long Running Command Storage 

Macro dsifind retrieves a pointer to storage for a long running command processor 
and returns the storage address in register 1. A prior dsipush instruction named 
the storage pointer. 

If two storage pointers were given identical names, dsifind retrieves the most 
recent storage address with the specified name, dsifind can be issued in an imme- 
diate command. Refer also to macros dsipush and dsipop. 

mvt addressability is required. 



[name] DSIFIND SWB = {(register)\symbolic name} 

[,LIST = {{register) [symbolic name}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). The tib address in swbtib must be correctly set. 

LIST 

Register containing the address of the parameter list used by the service 
routine, or symbolic name of that list. Do not specify this as register 1; register 
1 contains the swb address within dsifind. Do not put this list in the swb that is 
to be passed to dsifind. 

The parameter list is mapped by swblrcpl and contains the following fields. 
Hex Offset Length Field 

4 swblrcln (Length) 

4 16 swblrcnm (Name) 

Where: 

SWBLRCLN 

Specifies the parameter list length. Set swblrcln equal to swblrcfi 
(decimal 20). 

SWBLRCNM 

Specifies the name of the storage to be located. The storage address is to 
be returned to register 1. Specify this field exactly as you specified it in the 
corresponding macro dsipush. Instruction for specifying the name field are 
under "DSIPUSH - Establish Long Running Command" on page 202. 

Return Codes in Register 15 

Function was successful; storage pointer was retrieved and storage address 
was returned. 

32 Invalid macro invocation. Fix assembly errors before trying to run the 
program. 

36 Specified name was not found. 
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DSIFRE - Free Storage 



Macro dsifre must be used to release storage that was obtained using macro 
dsiget. Storage that was not obtained with dsiget cannot be released using dsifre. 
Optionally, dsifre dequeues the storage from the user's task vector block (tvb). 

Registers 2 through 12 may be used for register notation, dsifre always generates 
reentrant code. 

mvt addressability is required. 



[name] DSIFRE LV = {n|(reg/ster)} 

,A = {(regi$ter)\$ymbolic name} 

[,SP = {{register)\n umber}'] 

[,Q={YES|NO}] 

IJASKA- {(register)\symbolic name}] 

[,AQ = {YES|NO}] 



LV 

Number of bytes, or a register that contains the number of bytes, of storage to 
be freed. This option is ignored if q=yes is specified. 

A 

Register, or symbolic name of a fullword area on a fullword boundary, con- 
taining the address of the storage to be freed. 

SP 

Subpool number, or a register loaded with the subpool number, from which the 
storage is to be freed. Values through 255 are acceptable; is the default 
value. 

Q 

Indicates whether the storage is to be dequeued from the user's tvb. The 
option specified for this parameter must correspond to the option specified for 
the q parameter in dsiget that was used to obtain storage. 

Note: Do not modify the two words immediately preceding the queued 
storage. Otherwise, an abend may result. 

TASKA 

Register containing the address of the task vector block (tvb), or symbolic 
name of the tvb for this task. If this parameter is not specified, the default is 
dsitvb, and addressability to the dsitvb is required. 

AQ 

Indicates whether all queued storage is to be released. If you specify aq you 
cannot specify i_v or a. 

Return Codes in Register 15 

The mvs and vm/sp return codes for dsifre are in Register 15: 

Function was successful; storage was freed and dequeued, if requested. 

4 Storage was found on the queue and was dequeued but was not freed 
(freemain failure). 

20 Storage was not found on the queue. 
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DSIGET - Get Storage 



dsiget obtains storage. Optionally, dsiget can be used to queue the obtained 
storage to your task vector block (tvb). Storage obtained with dsiget must be 
released using dsifre. 

Registers 2 through 12 may be used for register notation, dsiget is intended to 
allow you to queue storage on the tvb chain so that NetView can free the storage at 
logoff. 

mvt addressability is required. 



[name] DSIGET LV={n|(reg/ster)} 

,A = {{register)\symbolic name} 

C.SP = {(register) | number}] 

C.LOC = {RES|BELOW| ANY|TEST}] 

r.BNDRY= (PAGEl DBLWP n 

[.CLEAR = {NO | YES}] 

[,Q={YES|NO}] 

[,TASKA = {(register)\$ymbolic name}] 



LV 



Number of bytes, or register containing the number of bytes, of storage to be 
obtained. The value must be positive. 

Register containing the address of the fullword area on a fullword boundary 
into which the address of the obtained storage is returned, or symbolic name of 
that fullword area. 



SP 



Subpool number, or register containing the subpool number, from which the 
storage is to be obtained. Values through 255 are acceptable; is the default 
value. 

LOC 

In vm and in mvs/370, this parameter is ignored. In mvs/xa, this parameter speci- 
fies where to allocate storage. 

RES 

Allocate storage that is consistent with the residency of the caller. 

BELOW 

Allocate storage below 16 Mb. 

ANY 

Allocate storage anywhere. 

TEST 

The caller of dsiget has set the high order bit of register 15 to indicate the 
type of storage desired. A in the high order bit means allocate storage 
below 16 Mb; a 1 means allocate storage anywhere. 

BNDRY 

Specifies the alignment of obtained storage. 
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PAGE 

Specifies that obtained storage is to be aligned on a page boundary. 

DBLWP 

Specifies that obtained storage is to be aligned on a doubleword boundary. 

CLEAR 

Specifies whether the allocated storage is to be initialized to zero. 

Q 

Indicates whether the obtained storage is to be queued to your tvb. The option 
specified for this parameter must correspond to the option specified for the Q 
parameter in dsifre that is used to free the storage. 

TASKA 

Register containing the address of the tvb for this task, or symbolic name of 
that tvb. If this parameter is not specified, the default is dsitvb and address- 
ability to the dsitvb is required. 

Return Codes in Register 15 

The mvs and vm/sp return codes for dsiget are in Register 15. 

Function was successful; storage was obtained. 
4 No storage was obtained. 
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DSIKVS - Keyword/Value Services 



Macro dsikvs is used in a command processor to determine whether an operator is 
authorized to use a given keyword or value. 

The return code shown in register 15 indicates whether the operator who issued 
the command has been authorized to issue it with the particular keyword, value, or 
both. 

mvt addressability is required. 

[name] DSIKVS S\NB = {(register)\symbolic name} 

{,CMD = {(register)\symbolic name} 1 

,SCTADDR = {(register) | symbolic name} j 
.KEYWORD = {(register)\symbolic name} 
[.VALUE = {(register)\symbolic name}"] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

CMD 

Register containing the address of an 8-byte field with the command name left- 
justified and padded with blanks, or symbolic name of that field. 

SCTADDR 

Register, or symbolic name of a fullword area, containing the address of the 
sct entry for the command that is to be checked. 

KEYWORD 

Register containing the address of an 8-byte field, or the symbolic name of an 
8-byte field, that contains the keyword, left-justified and padded with blanks. 
The parameter is required. 

VALUE 

Register containing the address of an 8-byte field, or the symbolic name of an 
8-byte field, that contains the value, left-justified and padded with blanks, value 
is specified when valclass checking is desired. 

Note: If both keyword and value are specified, keyword is scope-checked before 
value. If keyword results in a nonzero return code, value is not checked. 

Return Codes in Register 15 

The specified keyword and value, if given, are in the operator's scope of com- 
mands. 

4 The specified keyword was not in this operator's scope of commands. 

8 The specified value was not in this operator's scope of commands. 

12 A required parameter was missing, or an invalid parameter was specified in 

DSIKVS. 

16 Working storage could not be obtained. No storage is available. 
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DSILCS - Obtain/Release Control Blocks 

Macro dsilcs performs one of the following actions: 

• Obtains an swb for the caller and places the address of that swb in a fullword 
area specified by the cbaddr parameter 

• Releases an swb 

• Obtains a command work block (cwb) for the caller and places the address of 
that cwb in a fullword area specified by the cbaddr parameter 

• Releases a cwb 

• Locates a tvb by operator identification or by lu name 

• Locates, from a specified starting position, the next active tvb for a 
NetView-NetView task (nnt), a hard-copy task (hct), an operator station task 
(ost), or an optional task 

• Locates a tvb for an operator designated as a receiver of authorization mes- 
sages by the auth statement of a profile definition. 

mvt addressability is required. 



{name] DSILCS CBADDR = {{register) \symbolic name} 
[,LOC= {RES |ANY|TEST| BELOW}] 
,CWB = {GET|FREE} 
,SWB = {GET|FREE} 
JVB = {{register) \ symbolic name} 
,LU = {(reg/ster)|symoo//c name} 
,OPID = {{register)\symbolic name} 
l,NEXT={OST|HCT|NNT|OPT(PPT} J 
,AUTHRCV={YES|NO} 



CBADDR 

For the get and tvb options, register containing the address of a user-provided 
fullword area on a fullword boundary, or symbolic name of that area. The 
specified swb, cwb, or tvb address is returned to this area. 

For the free option, cbaddr contains the control block address. 

LOC 

Used with cwb=get or swb=get to determine the residency of the work block 
you are requesting (for mvs/xa only). 

RES 

Obtain a work block in storage consistent with the residency of the caller. 

ANY 

Obtain a work block anywhere in storage. 

BELOW 

Obtain a work block below 16 Mb. 

TEST 

The caller of dsilcs has set the high order bit of register 15 to indicate the 
type of storage desired. A in the high order bit means allocate storage 
below 16 Mb, and a 1 means allocate storage anywhere. 
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CWB 

Specifies the type of operation to be performed on the cwb. 

GET 

Specifies that the caller needs a cwb. The address of the cwb is returned 
to the area specified by the cbaddr parameter. Before you request 
NetView services, you must initialize the cwbtib field with the address of 
your tib. 

FREE 

Specifies that the caller wishes to release the cwb whose address is found 
in the area specified by the cbaddr parameter. 

SWB 

Specifies the type of operation to be performed on the swb. 

GET 

Specifies that the caller needs an swb. The address of an swb is returned 
to the area specified by the cbaddr parameter. Before you request 
NetView services, you must initialize the swbtib field with the address of 
your tib. 

FREE 

Specifies that the caller wishes to release the swb whose address is found 
in the area specified by the cbaddr parameter. 

TVB 

Value is either: 

1. Register containing the address of the tvb where the routine begins the 
search for the tvb specified by lu, opid, or next 

2. Symbolic name of an area containing the address of this tvb. 

tvb must be used with lu, opid, or next, and tvb must not be used with swb, cwb, 

Or AUTHRCV = YES. 

The address of the beginning of this tvb chain is found in the mvttvb. The tvb 
address found is placed in the area specified by cbaddr after the routine has 
completed processing. 

Note: The routine searches the address once to the end of the tvb chain; it 
does not loop to the beginning of the tvb chain. 



LU 



Used with tvb, register containing the address of an 8-byte lu name field, or 
symbolic name of that field. This name locates a tvb with a matching lu name. 



OPID 

Used with tvb, register containing the address of an 8-byte operator identifica- 
tion field, or symbolic name of that field. This name locates a tvb with a 
matching operator identification. 

NEXT 

Used with tvb, specifies the tvb to be located for the next task. 

OST 

Specifies that the tvb associated with the next active operator station task 
is to be located. 

HCT 

Specifies that the tvb associated with the next active hard-copy log task is 
to be located. 
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NNT 

Specifies that the tvb associated with the next active cross-domain task is 
to be located. 

OPT 

Specifies that the tvb associated with the next optional task is to be 
located. 

PPT 

Specifies that the tvb associated with the next active primary programmed 
operator interface task is to be located. 

AUTHRCV 

Specifies that the routine is to search for the first tvb to locate an operator 
authorized to receive messages related to successful and unsuccessful logons 
and lost station messages. See the discussions of the auth statement and 
unsolicited message routing in NetView Administration Reference. 

Return Codes in Register 15 

Function was successful. The address was returned, or the control block was 
released. 

4 No active tvbs of the type specified were found. 

8 If tvb was specified, end of the tvb chain was reached, or invalid opid was 
provided. 

8 If swb=get or cwb=get was specified, no storage was available. 

8 If swb=free or cwb=free was specified, defective control block. 

12 Invalid parameters were passed to dsilcs. 



176 NetView Customization: Assembler 



DSILOD - Load User-Defined Module 



Macro dsilod loads a user-defined module. You specify the name of the module to 
be loaded. 

mvt addressability is not required. 



[name] DSILOD fEP = modulename\ 1 

\ EPLOC = {(register)\symbolic name} J 



[,DCB = {(register) | symbolic name}"] 
[,LISTA = {(register)\symbolic name}] 
[,DPR = {(reg/sfer)|MVTDPRAD(,MVTPTR)}] 



Note: ep or eploc must be specified, but not both. 

EP 

Specifies the name of the module to be loaded. 

EPLOC 

Register, or symbolic name of an 8-byte field, containing the modufename to 
be loaded. The modulename should be left-justified and padded with blanks. 

OCB 

Register, or symbolic name of an area, containing the address of the dcb for a 
partitioned data set to be searched for the module. For mvs/xa, the dcb must 
reside below 16 Mb. The dcb is ignored in vm. 

LISTA 

Register containing the address of a 64-byte bldl directory entry list, or sym- 
bolic name of that list. In vm/sp and mvs, this parameter is ignored. It is 
retained only for compatibility with NetView Release 2 vse. 

DPR (required for NetView Release 2 vse only) 

In vm/sp and mvs, this parameter is ignored. However, if you want to write a 
routine to compile and run on both a NetView Release 2 vse system and on a 
NetView Release 3 mvs or vm/sp system, you will need to include this param- 
eter. In vse, this parameter specifies a register containing the address of the 
NetView dispatcher (dsidprnv), or mvtdprad(,mvtptr), where mvtptr is the sym- 
bolic name of a fullword area that contains the address of the mvt. 



Return Codes in Register 15 

Zero Module has been loaded. 

Nonzero Module has not been loaded. 



If the module is successfully loaded, register contains the load point address of 
the module. Register 1 contains the authority code in the high-order byte and the 
module length (in double words for mvs and vm) in the low-order three bytes. 

If the module has not been loaded, register 15 contains the return code returned by 
the system load facility. Register 1 contains the abend code and register contains 
the reason code for the abend. 

The module is loaded in virtual storage consistent with the linkage editor attribute 
rmode. If amode=24, the module is called in 24-bit mode, otherwise it is called in 
31-bit mode. 
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DSIMBS - Message Buffer Services 



Macro dsimbs puts variable text combined with message text into a buffer that you 
provide, dsimbs can determine the size of the buffer required to accommodate the 
message to be built. 

You can supply variable fields to be inserted into NetView messages or unique 
messages of your own with up to nine varying positional fields. 

mvt addressability is required. 



[name] DSIMBS SWB = {(register)\symbolic name} 

' MlD = {nnn\{register)\$ymbolic name\*equatename} 
,P1 = (text,lngth[,padlng,side,fillj) 



P9 = {text,lngth\_,padlng,side,fitQ)_ 
I ,MSGA = {pdb1addr,pdb2addr) 
BFR = {(register)\symbolic name} 1 

MSGSIZE = {{register)\symbolic name} J 
[, MSGTBL = {{register)\symbolic name}] 
[,OPT=CONCAT] 



(: 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

MID 

Identifies the message to be edited for the user. The message may be speci- 
fied by the message number {nnn), in a register, in a user area specified by 
symbolic name, or by the equate name preceded by an asterisk. For example, 

for MSG999 EQU 999, yOU COUld Specify MID = MSG999. 

P1...P9 

Used only in combination with the mid parameter, these values specify the 
positional fields in a message that are to be replaced by user-supplied text. 
The first two values, text and Ingth, must be specified; the others are optional. 



text 



Address of the variable text or the symbolic name of the area with the text 
to be substituted into the edited message. 

Ingth 

Length of the variable text to be substituted into the edited message. The 
maximum length is 255 characters, specified in character format. It can be 
a binary value in a register or in a user area specified by symbolic name. 
The user area must be a 4-byte fullword. 

padlng 

Length of the variable field to be padded with fill characters. This length 
must be equal to or less than the length specified by the Ingth parameter. 
The maximum length is 255 characters, specified in character format. It 
can be a binary value in a register or in a user area specified by symbolic 
name. The user area must be a 4-byte fullword. 
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side 

May be specified as L for left-fill or R for right-fill. The default is R. 

fill 

The fill character for the area to be padded. The default fill character is a 
blank (hex 40). 

MSGA 

The following registers are used for variable field substitution in message 
texts: 

pdbladdr 

Address of the pdb or the symbolic name of a fullword area with the 
address of the pdb. This address contains the addresses and lengths of the 
variable fields to be substituted into the message text. 

Note: Because the variable field information is contained in pdbladdr, the 
P1...P9 parameters may not be used with msga. 

pdb2addr 

Address of the pdb or the symbolic name of a fullword area with the 
address of the pdb. This address contains the message skeleton to be 
edited. This is not a NetView message; you supply the message. 

BFR 

Register, or symbolic name of a fullword area, containing the address of the 
buffer in which the edited message is to be returned, bfr must have an initial- 
ized bufhdr. Macro dsimbs initializes the hdrmleng, hdrdomid, and hdrtstmp 
fields. 

MSGSIZE 

Register containing the address of a user-provided fullword area, or symbolic 
name of that area. Use msgsize only to request the service routine for deter- 
mining the size of the buffer needed for the message to be edited. When the 
routine has completed processing, the required size is returned in this area. 

MSGTBL 

Register, or symbolic name of a fullword, containing the address of a user- 
defined message table. Macro dsimds generates this table. 

OPT 

Tells NetView to search dsimdm for a specified message identifier that cannot 
be found in the specified private message table (msgtbl). If opt=concat is 
omitted, NetView searches only the private message table for the message 
identifier. 

Return Codes in Register 15 

Function was successful. (1) The edited message is in the provided buffer 
and the length of the message is stored in the message length field of the 
buffer header, or (2) the size of the message buffer required has been calcu- 
lated and stored in the area specified by msgsize. 

4 The edited message is in the provided buffer, but the message skeleton con- 
tained a parameter for which the caller did not supply text. The message 
contains the characters &n where n may be from 1-9. 

8 Unsuccessful. The buffer overflowed, and the message has been truncated. 
The size of the truncated message has been stored in the message length 
field of the buffer header. 
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12 The message number specified could not be found in the NetView or user- 
specified message table. The message oooi was edited into the caller's buffer. 
If only the buffer size was requested, the size of message oooi is returned. 

16 The caller did not supply a buffer address. 

20 Combined conditions 4 and 8 occurred. 

24 Combined conditions 8 and 12 occurred. 

28 A validity check failed on the user message definition module. The address 
passed in the msgtbl parameter does not point to a message definition 
module that was created with macro dsimds. 

32 Storage request failed. 

36 i/o error. 

40 Unexpected end-of-file found. 
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DSIMDS — Message Definition Services 



Macro dsimds generates a message definition module to be used by macro dsimbs 
to display messages in user exits, command processors and subtasks. 

After a message definition module has been coded, it must be assembled and link- 
edited into a NetView load library, dsimds has no return codes. 

mvt addressability is not required. 

Three forms of dsimds are required to generate a message definition module. 
These forms are described in the following three formats; they must be coded in 
the sequence shown. 

Format 1: Start Message Definition Module Statement 



name DSIMDS prefix 

.TYPE = START 

.SEARCH = {I|D|B} 
[,MAXLEN= {71 1142|213}] 



name 

Required parameter that starts the message definition module. The name 
specified becomes the csect name for the module. The name can be any valid 
name which does not conflict with an existing NetView load module name. 

prefix 

Required positional parameter that becomes the 3 character prefix for the mes- 
sages in the module. The prefix should not conflict with the NetView message 
prefixes (aau, bnj, cnm, dsi, or dwo). 

TYPE 

Specifies the beginning of generation for the message definition module. 

SEARCH 

Indicates where the messages can be found: in the message definition 
module, on disk, or both, search causes a message definition module to be 
built. This indicator becomes part of the message definition table. 



T 



B 



Indicates the messages can be found only in the message definition 
module. (Default) 

Indicates the messages can be found only on disk. Individual message 
statements using Format 2 of dsimds should not be coded for the messages. 
The individual messages are coded on disk. Refer to "Defining Messages 
on Disk" on page 183. 

Indicates some of the messages can be found in the message definition 
module, and the others can be found on disk. Individual message state- 
ments using Format 2 of dsimds should only be coded for those messages 
that will not be defined on disk. Refer to "Defining Messages on Disk" on 
page 183. 
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MAXLEN 

Defines the maximum message length, maxlen is determined by calculating 
the length of "pppxxxt msgtext" (message number, type, a blank, and text). 
maxlen should be a multiple of 71. Maximum message size allowed is 213 
characters. If maxlen is not specified, message size defaults to 142 characters. 

Format 2: Define Individual Messages Statement 



[7aoe/] DSIMDS xxx,' message text [&&n]' 
.TYPE = {A|l} 



label 

Optional label. 

xxx 

Message number. It may be any number from 000-999. When dsimbs is issued 
to build the message, it will create the message identifier by concatenating 
your three-character prefix, the message number, and the type. 

When coding your message csect, you must code a message 000 statement to 
be issued when an invalid message number is specified. Message 000 should 
have one insert (&&1) which will contain the invalid message number. You 
may want to use wording similar to NetView's message dsioooi: 

MSG000 DSIMDS 000,'MESSAGE &&1 ISSUED BUT DOES NOT EXIST IN 
MESSAGE TABLE DSIMDM - CALL IGNORED', TYPE=I 

You should replace dsimdm with the name of your message table definition 
module; that is, the name specified on the dsimds type = start statement. The 
dsimbs service routine will substitute the message number of the invalid 
message in place of &&1. 

Note: At coding time, be sure that the buffer passed to dsimbs is big enough to 
hold the message with ail the inserts substituted. Otherwise, the message will 
be truncated. 

message text 

Text of the message added or changed. 

&&n 

Optional information may be substituted in the message at the place where the 
&&n occurs. The positional fields are specified by the Pn parameter in the 
dsimbs macro. &&1 - &&9 may be specified. 

TYPE 

Specifies the message type. 



Specifies an action message, one for which appropriate action must be 
taken. 



Specifies that the message is for information only. No specific action is 
required. 

Format 3: End Message Definition Statement 
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TYPE 

Specifies the end of the message definition module. This is the last statement 
specified. 

Note: The type - end statement should be followed by an assembler end state- 
ment. 

Defining Messages on Disk 

Messages can be defined on disk instead of, or in addition to defining them in the 
message definition module. The benefits of defining messages on disk are: 

• The message coding is simpler and does not require assembling and link- 
editing the message definition module when messages are added or changed. 

• The messages are read in by NetView when the dsimbs macro is issued. Mes- 
sages can be changed while NetView is running and the changes take effect 
immediately. 

Note: Messages that will be issued from code running with tvbinxit on cannot 
be read from disk. These messages must be defined in your message defi- 
nition module with Format 2 dsimds statements. 

Messages are coded in members in the NetView dsimsg data set (filetype nccflst, 
for vm). The member names (file names, for vm) must be in the format of DSipppxx 
where: 

ppp is the message prefix which was defined on the dsimds start message defi- 
nition module statement. 

xx is the first two digits of the message number. Up to ten messages can be 
defined in a member (xx0-xx9). 

The message syntax for the user messages is: 
xxx? message text [&n] 



XXX 

Message number. It may be any number from 001-999. 

t 

Message type: 

A 

Specifies an action message, one for which appropriate action must be 
taken. 

I 

Specifies that the message is for information only. No specific action is 
required. 

message text 

Text of the message added or changed. 
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&n 

Optional information may be substituted in the message at the place where the 
&n occurs. The positional fields are specified by the Pn parameter in the 
dsimbs macro. &1 - &9 may be specified. 

User Message Definition Module Example 

Following is an example of defining five user messages (usrooi - usroos). Message 
usrooi will reside in the message definition module called usrtable. Messages 
USR002 - usroos will reside in the NetView dsimsg data set under the member name 

DSIUSROO. 



Message Table Definition Module USRTABLE 



USRTABLE DSIMDS USR,TYPE=START,SEARCH=B 

MS6000 DSIMDS GOO,' USER MESSAGE &&1 ISSUED BUT DOES EXIST IN MESS* 

AGE TABLE USRTABLE - CALL IGNORED.' ,TYPE=I 
MSG001 DSIMDS 001,'THIS IS USER MESSAGE 1\TYPE=I 

DSIMDS TYPE=END 

END 



NetView DSIMSG Member DSIUSROO 



0021 THIS IS. USER MESSAGE 2 
003A THIS IS USER MESSAGE 3, RETURN CODE = &1 
0041 THIS IS USER MESSAGE 4, ftl IS TODAY'S DATE 
0051 THIS IS USER MESSAGE 5, TIME IS &1 
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DSIMQS - Message Queuing Services 



Macro dsimqs sends a user-supplied message or command to the message queue 
of a task's tvb. 

This message or command appears on the operator's screen or hard-copy log, 
depending upon which identification is specified. Buffers that are formatted as 
internal function requests (ifrs) are not displayed. Instead, they cause the 
receiving subtask to take the action requested by the ifr. Buffers that are for- 
matted as ifrs should not be sent to the authorized receiver (see authrcv operand 
below). 

mvt addressability is required. 



[name] DSIMQS SWB = {(register)\symbolic name} 
,BFR = {(register)\symbolic name} 
,TASKID = {(register)\symbolic name\PPT} 
,AUTHRCV={YES|NO} 
, LIST = {(register) | symbolic name} 
[.EXCEPT = {{pointer)\symboiic name}] 
[,BFRFLG = {YES|NO}] 
[,PRI = { NORM AL I HIGH 1 LOWI (register) [symbolic name}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

BFR 

Register, or symbolic name of a fullword area, containing the address of a 
buffer. (If dsiget obtained this buffer, the dsifre must free it after use. Use the 
same option for the Q parameter for both dsiget and dsifre.) bfr must have an 
initialized bufhdr. 

Note: Specify one, and only one, of the following: taskid, authrcv=yes, or list. 

TASKID 

Register containing the address of a user-provided 8-byte area, or symbolic 
name of that area, or ppt for the Primary poi task. The area should contain the 
8-character operator identification (tvbopid) of the task for which the message 
is to be queued. 

AUTHRCV 

Specifies that the first operator designated as the receiver of authorized mes- 
sages (by the auth statement of profile definition) is to receive the message. 
All messages sent to the authorized receiver are routed first to the ppt to test 
for automation and message routing (via the assign command). If not sup- 
pressed by automation or handled by routing, the messages are sent to the 
authorized receiver, if one is logged on, or to the system console. The authrcv 
option must only be used for messages. If the buffer to be sent is formatted as 
an internal function request (ifr) and it is not an automation ifr containing a 
message, the dsimqs macro will fail with a return code 4 (invalid buffer format) 
in register 15. See the discussions of the auth statement and unsolicited 
message routing in NetView Administration Reference. 
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LIST 

Pointer to, or symbolic name of, a fullword area containing the address of a list 
of operator ids or group ids to receive the message. Operators are assigned to 
groups using the assign command. See NetView Operation for more informa- 
tion on the assign command. 

• If 1ST is specified as the list type, the first logged on operator in the list will 
receive the message. (The first logged on operator may be in a group.) 
The receiving operator id is returned in the mqsentto field in the swb. 

• If all is specified as the list type, and a return code of was received, the 
message was sent to all specified operators and groups of operators in the 
list who were logged on. While the message was sent to all specified 
logged on operators, it was not necessarily received. 



• 



If multiple operator or group ids are specified, the last two fields (shown in 
the id list below) must be repeated for each operator or group listed. 



The id list has the following format: 

Hex Contents 

Offset 



1ST or all (three bytes) 



Number of ids in list (one byte) 



Unused (eight bytes) 



C Operator or group id (eight bytes) 

EXCEPT 

May be specified only if list is specified. This parameter specifies an eight- 
character field that contains an operator or group id, left justified and padded 
with blanks, that should not receive the message. 

BFRFLG 

Specifies whether the subtask that sends the buffer has released control and 
responsibility for it (bfrflg=yes). (With bfrflg=yes, the buffer must include 
hdrmcext with hdrsendr initialized.) bfrflg = no indicates that the receiving 
subtask is to make a copy of the buffer and return it. 

PRI 

Specifies a priority for message processing by the destination task. The value 
is either one of the three strings high, normal, or low, or a register or name of a 
full word area containing one of the three values defined in dsiswb. mqshi, 
mqsnorm, or mqslo. The default value is normal. A message or command sent 
at high priority would begin processing after any normal message currently in 
progress, but before other queued normal messages. A message or command 
sent at normal priority would similarly pre-empt a queue of low priority mes- 
sages. Of the NetView supplied tasks, only destination task types ost, ppt, and 
nnt respect priority. For destination tasks that have not indicated support for 
multiple priorities, dsimqs automatically converts all messages to normal pri- 
ority. 
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Return Codes in Register 15 

Function was successful; the message is queued. 

4 The format of the buffer that was passed was invalid. 

8 The task is inactive, or no task was identified as a receiver for the buffer. 

12 A buffer could not be obtained. 

16 NetView is terminating. 

20 swb address is invalid. 

22 The list specified with the list option contained no operator ids. It contained 
only unassigned group ids. 

23 Messages were routed to the first 255 operators and/or groups. 

24 An invalid value was specified for priority. 
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DSIOIS - Operator Identification Services 



Macro dsiois searches the operator identification table (dsioit) in preparation for 
span authority checking using osisss. 

dsiois returns the relative position of the entry to a user-provided fullword area. 

mvt addressability is required. 



[name} DSIOIS SWB= {(register)\symbolic name} 
,OPID= {{register)\symbolic name} 
,OITPOS = {(register)\symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

OPID 

Register containing the address of an 8-byte, left-justified operator identifica- 
tion field; or symbolic name of that field. 

OITPOS 

Register containing the address of a fullword area, or symbolic name of that 
area. When the routine has located the specified operator identification in 
dsioit, that entry's relative position is returned to this fullword area. For 
example, the third entry results in a fullword 3 being returned. 

Return Codes in Register 15 

Function was successful; the position of the entry is returned. 

4 Unsuccessful. The entry was not found in dsioit. 
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Macro dsipas receives a command parameter as input and searches the system 
command table (sct) to determine whether the entered parameter is an alias for 
the actual parameter. 

If the parameter is an alias, the regular value is returned to a user-provided area. 
If it is not an alias, the input value is returned to the user area. If the value is 
invalid, blanks are returned to the input area. 

mvt addressability is required. 



[name"] DSIPAS SWB = {{register)\$ymbolic name} 

,PDB~{(pdbreg)\pdbname,(entreg)\entname\' entry'} 
,OUT = {{register) \symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

PDB 

Specifies two values. The first value is the address of a pdb and the second 
value is the entry number of the field in the pdb to be examined. 

pdbreg 

Register that contains the address of the pdb. 

pdbname 

Symbolic name of a fullword that contains the address of the pdb. 

entreg 

Entry number, right justified. 

entname 

Symbolic name of a fullword that contains the entry number, right justified. 

entry 

Constant that specifies the entry number. 

Note: pdbcmda must contain the address or pointer to an entry in the sct. 

OUT 

Register containing the address of a user-provided 8-byte area to which the 
NetView equivalent of the input parameter is returned if found, or symbolic 
name of that user area. 

Return Codes in Register 15 

A regular parameter value was returned. 

4 No equivalent was found; the same parameter is returned. 
8 Invalid parameter; blanks are returned. 
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DSIPOP - Remove Long Running Command 



Macro dsipop removes a long running command element that dsipush placed on the 
stack. 

The element canceled is the one nearest the top of the stack with the name speci- 
fied in the parameter list. If a calling command procedure is suspended by 
dsipush, use dsipop to let the command procedure continue at the next instruction. 
The command procedure continues when the resume routine or currently running 
command returns control to the ost or ppt. 

Do not use dsipop while in a logoff routine, an abend reinstate routine, or an 
immediate command. 

Refer also to macros dsifind and dsipush. 

mvt addressability is required. 



[name] DSIPOP SWB = {{register)\symboiic name} 
,LIST= {{register)\symbolic name] 
[,COMPCDE = {(register)\symbolic name}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). The tib address in swbtib must be correctly set. 

LIST 

Register containing the address of a parameter list used by the service routine, 
or symbolic name of that list. Do not specify this as register 1; register 1 con- 
tains the swb address within dsipop. Do not put this list in the swb that is to be 
passed to dsipop. 

The parameter list contains the following fields: 
Hex Offset Length Field 

4 swblrcln (Length) 

4 16 swblrcnm (Name) 

Where: 

SWBLRCLN 

Specifies the parameter list length. Set swblrcln equal to swblrcpo 
(decimal 20). 

SWBLRCNM 

Specifies the name of the storage to be dequeued and freed. Specify this 
field exactly as you specified it in the corresponding macro dsipush. This 
16-byte field is used as is. Instructions for specifying the name field are 
under "DSIPUSH - Establish Long Running Command" on page 202. 

COMPCDE 

Specifies the value of the completion code for the long running command (lrc) 
being removed. The value may be specified as a register, symbolic name of a 
full word area, or a full word literal. The value is meaningful only if the lrc 
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being removed specified a resume routine and only if the process that created 
the long running command element (using dsipush) was directly invoked from 
another long running command. If you do not specify compcde, the value 
defaults to: 

if the lrc being removed is in control (top of stack) at the time dsipop is 

invoked. This is the usual (and recommended) case. 

-5 if the lrc being removed is not at the top of the stack. Negative five is 

treated as a cancel request by NetView command procedures and 
certain related commands. 

You can be certain that your lrc is at the top of the stack, when it is resumed. 

Note: NetView command procedures are long running commands. If a long 
running command you write is called from a command procedure, you can 
pass a return code to it using the compcde keyword. If a long running 
command you write makes a direct call to schedule a command procedure, you 
can obtain its return code upon resumption from cwbrcode. 

Return Codes in Register 15 

Function was successful; the long running command processor element is 
dequeued. 

16 Request issued while in an immediate command, or while NetView is cur- 
rently in an exit, a logoff, or an abend reinstate routine. 

32 Invalid macro call. Fix assembly errors before trying to run the program. 

36 Specified name was not found. 
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DSIPOS - ECB Post Services 



Macro dsipos indicates the completion of an event by posting an event control 
block (ECB). 

mvt addressability is required. 
[name] DSIPOS ecbaddress[,compcde'} 



ecbaddress 

Symbolic name of ecb or register (1-12) that contains the address of the ecb. 
If a register is specified, it must be enclosed in parentheses. 

compcde 

Value of the completion code to be placed in the ecb (0 - 16,777,215) or in a 
register (0, 2 - 12) that contains the value. If a register is specified, it must be 
coded in parentheses. If no value is specified, is assumed. 

Note: These parameters are positional; they must be specified in the indicated 
order. 
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IPRS - Parsing Services 



Macro dsiprs parses commands using specified or assumed delimiters, or deter- 
mines the size of the parse table required to parse the input buffer. 

The parse table describes the data contained in the buffer, dsiprs finds delimiters 
in the data and formats the pdb to indicate data segments separated by the delim- 
iters, dsiprs may be called again to build the parse table in a user-provided area. 

mvt addressability is required. 



[name] DSIPRS SWB = {(register)\symbolic name} 
,BFR = {(register)\symboHc name} 



{PDBSIZE = {{register)\symbolic name} 1 
,PDB = {(reg/ster)|symJ!>o//c name} J 



[,FIRST={YES|NO}] 
[,DEUM = ( , D1', , D2',... , Dn')] 
[,SUB = {YES|NO}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

BFR 

Register, or symbolic name of a fullword area, containing the address of the 
buffer to be used for input, bfr must have an initialized bufhdr. 

PDBSIZE 

Register containing the address of a fullword area to which the size of the 
parse table is to be returned, or symbolic name of that area. 

PDB 

Register containing the address of a fullword pointing to the area where the 
parse table is to be built, or symbolic name of that area. The parse table must 
include a user-initialized dsicbh header that contains the control block identifi- 
cation and length before the data can be parsed. 

FIRST 

Indicates whether the first word of the input buffer can be delimited only by a 
blank (yes) or by any delimiter (no). 

DELIM 

Allows you to specify delimiters instead of NetView defaults. NetView default 
delimiters are blank, comma, period, and equal sign. Blank is always consid- 
ered a delimiter, even if you specify your own delimiters. 

SUB 

Indicates whether all text within single quotes is to be parsed as one element 
(yes) or not (NO). This option treats everything between single quotes as one 
element provided the first quote is preceded by a delimiter and the last quote 
is followed by either a blank or comma. 
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For each example below, dsiprs is issued to pass the given character string with 
the default delimiters and sub = yes. 

Example 1 

RETURN CODE IS ' NON-ZERO ' . 

dsiprs will return the unbalanced quotes return code. 

Example 2 

RETURN CODE IS 'GOOD', CONTINUE. 

The following pdb table is built: 



PDBTYPE 


PDBLENG 


PDBDISP 


TOKEN VALUE 


5 


6 


24 


RETURN 


6 


4 


2B 


CODE 


b 


2 


30 


IS 


i 


4 


34 


GOOD 



8 



3B 



CONTINUE 



Example 3 

RETURN CODE IS (X'00'), CONTINUE. 

The following PDB table is built: 
PDBTYPE PDBLENG 



PDBDISP 



TOKEN VALUE 



b 


6 


24 


RETURN 


b 


4 


2B 


CODE 


b 


2 


30 


IS 


i 


2 


33 


(X 


• 


2 


36 


00 


t 


1 


39 


) 



3C 



CONTINUE 



Return Codes in Register 15 

Function was successful. The required size of the table was returned in 
pdbsize, or the command was parsed and the parse table was built. 

4 The input buffer was parsed, but there was no data in the input buffer (zero 
length data) or the data in the input buffer was all blanks. Only the buffer 
address and number of entries (0) could be returned in the parse table. 

8 The parse table size was too small for the input buffer; a partial parse table 
was built, and the number of entries was set to the number that the parse 
table could hold. The size of the parse table should be increased. 

12 Unbalanced quotes. Returned only if sub = yes is specified. 
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16 The number of characters between two consecutive delimiters in the input 
buffer was greater than 255. 

20 An unpaired Kanji delimiter or uneven number of Kanji data bytes was found 
in the input buffer. For example, one of the following may have occurred: 

• The end of the input buffer was found before the Kanji data-entering 
delimiter (SI). 

• A second Kanji data-beginning delimiter (SO) was found before the Kanji 
data-ending delimiter (SI). 

• An uneven number of Kanji data bytes was found between Kanji data 
delimiters. 

100 No pdb or an invalid pdb was passed. 
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DSIPSS - Presentation Services 



Macro dsipss writes a message to an operator's screen or sends messages to 
another NetView. The presentation service routines, which dsipss calls, control 
screen formats, organize data into a specific form for each device, and send the 
data. 

For mvs console tasks, system wto services are used to display messages in addi- 
tion to processing as described for unattended operator tasks. 

mvt addressability is required. 



[name] DSIPSS SWB = {{register) {symbolic name] 

[,APPLID= {{register)\symbolic name}] 
.TYPE = {OUTPUT|FLASH|IMMED|XSEND| 

SCRSIZE|WINDOW|ASYPANEL| 

PANEL|CANCEL|PSSWAIT| 

TESTWAIT} 
[,ECBLIST= {(register)\symbolic name}] 
[,BFR = {{register)\symbolic name}] 
[,SIZE= {(register)\symbolic name}] 
[ r PANEL= {{register)\symbolic name}] 
[.OPTIONS = {MSG|SEG| 

FIRST|MIDDLE| 

LAST|ONLY}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

APPLID 

Register containing the address of an 8-byte area that contains the name (left 
justified and padded with blanks) of the application program to which the data 
is to be sent, or symbolic name of that 8-byte area. This name should be the 
same as the name specified on the start command when a session is started. 
applid is specified only when type=xsend is specified. 

TYPE 

Type of presentation services routine to be called: 

OUTPUT routine 

Specifies that the routine is to send a message to the operator's terminal. 
Do not use this option in immediate command processors, in user exit rou- 
tines with TVBiNXiT set on, or in user exit DSIEX12. The maximum message 
length before truncation is 32,767 characters for ost and 256 characters for 
nnt. Upon completion of the macro, the length of the text in the hdrmleng 
field of the bufhdr is set to the length of the data after any trailing blanks 
have been truncated. 

dsipss calls dsiexo2a, message copy (assign), and logging functions. 

FLASH 

These messages are not suppressed by &wait processing, or message 
automation, nor are they logged (they can be logged prior to calling dsipss 
if you choose). They will be displayed regardless of the stifle state. 
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Note: For output and flash, if your data is formated as an automation ifr, 
it must be in buffers obtained with dsiget using q = no and subpool zero. 
dsipss will free the automation ifr structure. If your data is not formatted 
as an automation ifr, there is no restriction on the type of storage used 
and the storage will not be freed. You are responsible for freeing it. 

IMMED 

Specifies that the routine is to send a message to the operator station's 
immediate message area. The maximum message length before trun- 
cation occurs is 71 characters. Use this option only in immediate 
command processors or the dsiexoi user exit routine. When this parameter 
is specified, no message header information is sent to the display screen. 
type = immed terminates full-screen mode and causes subsequent terminal 
input to be treated as commands. 

dsipss calls dsiexo2a, message copy (assign), and logging functions. 

XSEND 

Specifies the routine is to send data to another NetView with which a 
session exists. (Sessions are started with the start domain = command.) 
The maximum data length before truncation is 240 characters. 

SCRSIZE 

Specifies the routine is to return the screen size in row-column format. 

WINDOW 

Requests information on the size of the output area of the standard screen. 
This option is valid only from an ost. Under any other task, the request is 
considered null; register 15 contains a return code of 0, but no function is 
performed. Three output area sizes are returned: 

• Minimum 

• Current 

• Maximum. 

The minimum window size may be used to produce screens that are inde- 
pendent of the current window size. The current window shows the screen 
size currently in effect. The maximum window size is useful for calculating 
the maximum storage needed to produce title-line panels. 

ASYPANEL 

Specifies that the issuing routine assumes control of the screen. Input and 
output will be formatted as 3270 data stream commands. Notification of 
input availability is done asychronously by the posting of ecbs. 

After a dsipss type = asypanel, input to the terminal will be treated as input 
to the process issuing the asypanel request until either a dsipss 
type = cancel or a dsipss type = output is issued. 

Full-screen mode is not supported for unattended operator tasks, including 
those associated with a system console. 

PANEL 

Although this option is supported for compatibility with earlier releases of 
NetView, it is not recommended. 

CANCEL 

Cancels pending asynchronous full-screen input. This option is used when 
changing the characteristics of the asynchronous full-screen processor, 
such as the ecb address or the panel address. type = cancel is allowed only 
from an ost. This option can be invoked regardless of whether a dsipss 
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type - asypanel is active or the input from type = asypanel has been posted 
as complete. 

After type = cancel is issued, no further input is received from the terminal 
until type=output, type =immed, type = panel, or type = asypanel is issued. 

PSSWAIT 

Specifies that a command is to wait for a list of its own events and a list of 
events that should be allowed to interrupt the command events. 
type * psswait is allowed only from an ost. 

Note: Use macro dsiwat if you do not want the command to wait for the 
completion of events. 

TESTWAIT 

Allows a command processor to test whether an event has occurred that 
should interrupt the asynchronous full-screen command processor. 
type=testwait is allowed only from an ost. This option can be used before 
a dsipss type = asypanel is issued to determine if the asynchronous full- 
screen panel input/output should be attempted. If dsipss type = psswait is 
used to wait for events, this option can prevent unnecessary screen 
input/output by allowing testing before panel input/output is requested. 

ECBLIST 

For type = psswait, register, or symbolic name of a fullword area, containing the 
address of an ecb list. An ecb list is a list of addresses of user-defined event 
control blocks that is copied and combined with an ecb list. NetView waits for 
this combined list; when one of the events associated with this list is posted, 
control is returned to the next sequential instruction. The input ecb list is made 
up of fullword ecb addresses. The last address in the list must have the first bit 
set on to specify that this is the last entry. 

BFR 

Register, or symbolic name of a fullword area, containing the address of a 
user-provided buffer. This buffer should contain the data to be processed, bfr 
is used only for type = flash, type = output, type =immed, and TYPE = XSEND. bfr 
must have an initialized bufhdr. 

SIZE 

For type = scrsize, register, or symbolic name of a fullword area, containing the 
address of a user-provided 4-byte area to contain the size of the display 
screen, in row-column format. For example, a 1920-character screen is 
defined as X'00180050\ since the screen is 24 rows (x'oois 1 ) by 80 characters 

(X'0050'). 

For type = window, a register containing the address of a 12-byte area, or sym- 
bolic name of that area. The window size is returned in binary to the area. 
The window size is the number of lines available for output on the screen. The 
size varies depending on screen size and the number of input lines specified 
on the input command. The format of the area is: 
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Bytes 
(Decimal) 


Bytes 
(Hex) 





(0) 


2 


(2) 


4 


(4) 


6 


(6) 


8 


(8) 


10 


(A) 


12 


(C) 



Minimum Window Size, Rows 
Minimum Window Size, Columns 
Current Window Size, Rows 
Current Window Size, Columns 
Maximum Window Size, Rows 
Maximum Window Size, Columns 

PANEL 

For type = asypanel, a register containing the address of a 20-byte parameter 
list, or the symbolic name of that list. The parameter list is formatted as 
follows: 



Bytes 
(Decimal) 


Bytes 
(Hex) 

(0) 

(4) 

(8) 

(C) 

(10) 

(14) 









ECB Adress 


4 


Output Data Stream Address 


8 


User Input Area Address 


12 


Output Length 


Input Area Length 


16 
20 


Data length Address 



If asynchronous full-screen output is requested, the output data stream address 
field contains the address of a 3270 data stream including a 3270 command, 
wcc, and orders to be written to the terminal. The command must be coded 
using remote ebcdic values. The output length field indicates the length, in 
bytes, of the 3270 data stream (32,767 bytes maximum). If output is requested, 
the ecb address, input area length, user input area address, and data length 
address fields are not used. 

To read asynchronous full-screen input from a terminal, the ecb address area 
contains the address of an event control block to be posted when the asynchro- 
nous input is received. The user input area address contains the address of a 
user area into which the full-screen panel data is read. If the length of the data 
being read is greater than the user input area, the data will be truncated in that 
area. The input area field indicates the length of the input data area in bytes 
(32,767 bytes maximum). The data length address field contains the address of 
a halfword field set to the amount of data read when the ecb is posted. 

OPTIONS 

Specifies the type of message to be sent, options is used only for type = output. 
The default is msg, which specifies that the data to be sent is a complete 
message. 

In general, title line output should be used instead of the other values for the 
options parameter. The other values are as follows: 

• seg, which specifies that the data to be sent has no message header. 

• first, which begins full-line mode. It specifies that the data is to start at 
the top of the screen, with full 80-byte line width. 

• middle, which continues full-line mode. 
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• last, which specifies the end of a full-line mode screen. The screen is 
locked until the operator signals for the screen to be refreshed. 

• only, which specifies that one full-line message is to be written at the top 
of the screen with the rest of the screen blank. 

Return Codes in Register 15 

Function was successful; the message is written. For type=psswait, an ecb 
has been posted. Check the ecb list to determine which event has completed. 
For type = asypanel, the send or receive request has passed NetView syntax 
and buffer checking and has been sent to vtam; it does not indicate the 
success or failure of vtam completion of the receive. The ecb post code must 
be checked to determine the success or failure of the asypanel request. The 
post code will be put into the ecb specified in the panel parameter list. 

4 For type=xsend, no rpl was found and no data was sent. 

8 Parameter error. There is an error in the formatting of the message buffer 
header. For type = xsend, the session is not active and no data is sent. For 
type= panel, the input or output length is invalid, that is, greater than 32,767 
bytes (X7FFF"). For type = asypanel, the parameter list is inconsistent. If the 
output buffer is specified, its length must also be specified. If the input ecb is 
specified, the input area address, input area length, and the data length 
address of the returned length must be specified. 

12 There is not enough storage available in NetView to complete the request. 
No output is sent, and the input command processor is not be scheduled. 

16 dsipss type = output was issued for an immediate command or in an irb exit 
routine. Use dsipss type = immed or dsimqs instead. Too many options = middle 
were specified, and the screen is full. This options = middle is treated as an 
options=last. If another middle is issued, it is treated as an options = first. 
The screen wraps around, and return code 24 is issued. The requested dsipss 
service could not be performed under this unattended operator task, mvs 
console operator task, ppt, or dst. 

20 No terminal session exists. For type= panel, the panel request came from a 
task other than an ost. No output is sent, and the input command processor 
is not scheduled. For type = asypanel, the panel request came from a task 
other than an ost. No input will be received. For type=cancel, the panel 
request came from a task other than an ost. 

24 For options = first, middle, last, or only, options were specified in an incorrect 
order. 

28 For options = first, middle, last, or only, user exit dsiexo2 specified that title- 
line output was to be deleted. The output was not written to the screen. This 
return code does not indicate a severe error, but rather warns that protocol 
for title-line mode may have been violated. 

32 For type = panel, no input command processor is scheduled. The operator 
requested escape to NetView mode by selecting option 1 when prompted by 
message DSI817A. 

36 For type= panel or type = asypanel, a temporary error occurred. The contents 
of the screen have been modified. Reformat the screen using an Erase/Write 
or Erase/Write Alternate 3270 command. Then retry the request. 
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40 A permanent input/output error occurred. Do not retry the request. No output 
will be sent, and no input processor will be scheduled. For type=asypanel, 
no input will be received. For type = cancel, NetView is unable to restart 
normal terminal activity. 

44 For type = panel, no input is scheduled, because the operator requested reset 
by selecting option 3 when prompted by message DSI817A. 

48 For type = asypanel, no input/output is scheduled because the command 

processor issued a second dsipss type = asypanel requesting input before the 
previous request had completed. 

56 For type = psswait or type =testw ait, at least one NetView ecb was posted. 

The ecb post codes for pss type = asypanel are found in the event control block if 
one was specified. They are as follows: 

Function was successful; the requested data is available. 

12 There is not enough storage available in NetView to complete the request. 
The output data was sent, but the input data is not available. 

36 A temporary error occurred during a full-screen read. Retry the request. The 
output data was sent, but the input data is not available. 

40 A permanent error occurred during a full-screen read. Do not retry the 
request. The output data was sent, but the input data is not available. 

52 The requested input was canceled by dsipss type = cancel. Do not retry the 
request immediately. The output data was sent, but the input data is not 
available. 



Chapter 8. Macro Reference 201 



DSIPUSH 



DSIPUSH - Establish Long Running Command 

Macro dsipush can perform either of two related functions: 

• Establish named storage 

A storage pointer passed to dsipush is associated with a 16 character name 
chosen by the dsipush caller. After a successful dsipush, the dsifind macro can 
be used to obtain the storage pointer from the name. All task types supporting 
commands also support named storage (ppt, ost, nnt, dst). 

• Establish resumable command 

A resumable command can return to its caller, with the assurance that the 
specified resume routine will be called when other scheduled activity for the 
task allows. Resumable commands may exit, for example, to wait for data 
requests to be satisfied or to allow queued "simulated terminal" commands to 
execute. All NetView components behave this way. Task types supporting 
regular commands also support resumable commands (ppt, ost, nnt). 

Both of these functions are "task level" operations, global for the task where they 
occur, but invisible from all other tasks. All requests define recovery 4 and termi- 
nation procedures. 

mvt addressability is required. 

When a command issues dsipush for a resume routine, the following applies: 

If a command invoked by a command procedure (NetView command list lan- 
guage, rexx, or high-level language) specifies major when issuing dsipush, the 
command procedure is suspended at that point until the resume routine is 
removed by dsipop. If such a command specifies minor when invoking dsipush, 
then the resume routine will be invoked following the completion of the 
command procedure. 

A command may schedule a command procedure and obtain a return code by 
taking the following steps: 

1. invoke dsipush for its own resume routine, 

2. make a direct call to schedule the command procedure, 

3. upon return from the direct call, exit to allow the command procedure to 
complete 

4. when the resume routine gains control, check the return code from the 
command procedure in cwbrcode. 

Notes: 

1. When a command procedure is canceled for any reason, its return code is -5. 

2. wait and pause statements in a command procedure called by a long running 
command do not cause premature calling of the resume routine. The resume 
routine is not scheduled until the command procedure completes. 

Do not use resume or abend reinstate routines under a dst. 



4 Note that dst tasks always terminate after any failure (abend), thus recovery routines are not appropriate under 
dst's. 
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Do not use dsipush while running in a logoff or abend reinstate routine specified on 
a previous dsipush, or while tvbinxit is on. 



[name] DSIPUSH SWB = {(register)\symbolic name} 
, LIST = {(register) \ symbolic name} 
. [,ROLL={YES|NO}] 
[.PROMOTE = {YES|NO}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). The tib address in swbtib must be correctly set. 

LIST 

Register containing the address of a parameter list used by the service routine, 
or symbolic name of that list. Do not specify this as register 1; register 1 con- 
tains the swb address within dsipush. Do not put this list in the swb that is to be 
passed to dsipush. dsipush will read, but not write to, your parameter list; nev- 
ertheless, reentrancy demands you put the parameter list in dynamic storage if 
your code updates any part of it (such as the storage pointer) at run time. 

The parameter list contains the following fields: 
Hex Offset Length Field 






4 


swblrcln = Length 


4 


16 


swblrcnm = Name 


14 


4 


swblrcst = Storage address 


18 


8 


swblrcre = resume routine 


20 


8 


swblrcab = abend reinstate routine 


28 


8 


swblrclg = logoff routine 



30 4 swblrcfg = Flags 



Where: 



SWBLRCLN 

Specifies the parameter list length. Set swblrcln equal to swblrcpu 
(decimal 52). 

SWBLRCNM 

Associates a name with your Long Running Command or storage address. 
You will use this name on subsequent calls to dsifind or dsipop. The name 
should be unique within a particular task, but a duplicate name used under 
another task does not interfere. A second use of dsipush for named 
storage with the same name under the same task will temporarily hide the 
first storage pointer. The first storage pointer becomes accessible (via 
dsifind) after dsipop is issued for the duplicate name. 

The name can be any combination of bits as long as you specify the name 
identically for all macro calls with the same name. Names beginning with 
dsi are reserved for NetView names. The name field is used as is; it is not 
padded or justified. 
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SWBLRCST 

Can be used to associate a storage address with the specified name. 
However, NetView makes no use whatsoever of the value specified; it is 
only returned when dsifind is invoked, specifying the same name. 

SWBLRCRE 

Specifies the load module name of the resume routine. If this field is 0, no 
resume routine is indicated. The load module named must have a corre- 
sponding cmdmdl statement. 

SWBLRCAB 

Specifies the load module name of the abend reinstate routine. This name 
must not be for tasks other than dst tasks. This name must be for dst 
tasks. The load module named must have a corresponding cmdmdl state- 
ment. 

SWBLRCLG 

Specifies the load module name of the logoff routine. This name must not 
be 0. The load module named must have a corresponding cmdmdl state- 
ment. 

SWBLRCFG 

Indicates whether the dsipush execution is minor or major. Bit is the indi- 
cator bit; it is defined when a resume routine is specified. When bit = 1, 
a minor dsipush is perfomed. When bit = 0, a major dsipush is perfomed. 
See "RESUME Routines" on page 64 for more information on major and 
minor invocations. When no resume routine is specified, this field is 
ignored. 

ROLL 

Specifies whether a long running command processor element has strict, 
global dependencies on other lrcs. 

All those lrcs created with roll=no will be serviced in strict fifo order for 
resume, abend reinstate, and logoff, lrcs created with roll = yes are regarded 
as being interrelated if they are all created during a single command invoca- 
tion or if they are created during a resume routine call. Note that if a command 
processor or resume routine makes a direct call (see "Calling a Command 
Directly" on page 21) to another command processor, dsipush still regards that 
command's processing as part of the original command's processing. All lrcs 
related in this way are processed in fifo order, with respect to each other. The 
processing of other, unrelated lrcs, may be in any order. 

When no resume routine is specified, you must specify roll=no or allow the 
value to default. When a resume routine is specified, roll=yes is the default 
and is strongly recommended. 

PROMOTE 

When yes is specified, a search is made of all previous dsipushs (excepting 
those since canceled via dsipop). If a dsipush with the same name is found, 
then the entire, related group associated with that name will be made the 
active group. 

If the group does not exist, the request is treated as an ordinary dsipush and a 
stack element is created. 

The storage specified in the invocation becomes the current storage associ- 
ated with the specified name (swblrcnm) and previous storage associated with 
the name will be returned to the caller in register 0. 
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promote may only be used with roll = yes (or by default) and only when a 
resume routine is specifed. 

When promote = no is specified and when the promote parameter is omitted, no 
search is performed. The dsipush is considered new and an lrc (possibly 
duplicate) is created. 

Return Codes in Register 15 

Function was successful; the long running command request is queued. 

4 Storage is not available for request. 

8 abend reinstate or logoff routine required but not specified. 

12 Request issued from invalid task: 

• resume request issued under dst 

• abend request issued under dst 

• dsipush issued and task is not ost, nnt, dst, or ppt. 

16 Request issued while in an immediate command or while NetView is currently 
in an exit, or in the middle of a logoff routine or abend reinstate routine. 

20 resume routine is a command list or the cmdmdl statement did not pass 
validity checking. 

24 abend reinstate routine is a command list or the cmdmdl statement did not 
pass validity checking. 

28 logoff routine is a command list or the cmdmdl statement did not pass 
validity checking. 

32 Invalid macro invocation. Fix assembly errors before trying to run the 
program. 

Note: If register 15 contains return code 20, 24, or 28, register will contain a sec- 
ondary return code. See "DSICES - Command Entry Services" on page 163 for 
an explanation of the return code in register 0. 
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DSIRDS - Resource Definition Services 



dsirds locates the specified resource in the authorization and routing table (art) 
and returns the address of the art entry to a user-provided fullword area. 

mvt addressability is required. 



[name] DSIRDS SVJB = {(register)\symbolic name} 

.LUNAME = {(register)\symbolic name} 
,ARTPOS= {{register)\symbolic name} 
[.STATUS = {ACT|INACT}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

LUNAME 

Register containing the address of a user-provided area, or symbolic name of 
that area. The area should contain the 8-byte, left justified luname to be 
located in the art. 

ARTPOS 

Register containing the address of a fullword area, or symbolic name of that 
area. When the routine has located the specified entry in art, that entry's 
address in the table is returned to this area. 

STATUS 

Specifies whether the luname entry in art is to be marked as active (act) or 
inactive (inact). 

Return Codes in Register 15 

Function was successful; the entry was found and its address was returned. 

16 No art. 

20 Unsuccessful. The specified entry was not found in art, or the entry is inac- 
tive. 
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DSIRXCOM - Access REXX Variables 



An assembler language program called from a rexx command list may wish to 
access the variables within the rexx command list which invoked it. Macro 
dsirxcom provides an interface to the gcs execcomm macro to obtain access to 
these variables, dsirxcom issues a gcscall setcomm macro to insure that the 
correct rexx Work Block is accessed and then issues the gcscall execcomm macro 
to access and manipulate the variables. 

Before invoking dsirxcom, you must build a chain of shared variable request blocks 
(shvblock) as described in the VM/SP System Product Interpreter Reference. 



[name] DSIRXCOM TIB = {(register)|symbolic name} 

,SHVB = {(register)|symbolic name} 



TIB 

Register containing the address of the task information block (tib) for this task 
or symbolic name of the tib. 

SHVB 

Register containg the address of the first shared variable request block 
(shvblock) or symbolic name of the shvblock. 



Return Codes in Register 15 

Successful. 



-1 Invalid entry conditions. 

-2 Insufficient storage. 

-3 No execcomm entry point found. 

Nole: For a more detailed explanation of the non-zero return codes, see the dis- 
cussion of execcomm in the VM/SP System Product Interpreter Reference. 
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DSIRXEBS - Get An EVALBLOK 



Macro dsirxebs is an interface to check the required interface parameters for 
getting aVM evaluation block (EVAlblok). 

The macro dsirxebs can be used instead of the tso/e macro irxrlt for the tso/e 
user. This macro is to be used by vm/rexx users for getting evaluation blocks. 

The size of the evalblok data area is passed. The header size is added to the data 
size, the appropriate doubleword area is obtained, and initialization of the area is 
performed. Parameters are passed in the system work block (SWB) which you 
provide. If you pass an evalblok address in the evbptr, that block is freed before 
the new block is obtained. 

mvt addressability is required. 

For additional information on dsirxebs, see Chapter 6 on page 109. 



[name] DSIRXEBS 



SWB = { {register) [symbolic name} 
.LENGTH = {(register)\symbolic name} 
.EVBPTR = {{register)\symbolic name} 
.ENVBPTR = {{register)\symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of an 

SWB. 

LENGTH 

Register, or symbolic name of a fullword area, containing the address where 
the evalblok data size is obtained. 

EVBPTR 

Register, or symbolic name of a fullword area, containing the address where 
the evalblok address is placed when it is obtained. If this area is not zero 
(X'00') initially, it is assumed that it contains an evalblok address to be freed. 

ENVBPTR (MVS/XA only) 

Register, or symbolic name of a fullword area, containing the address of the 
tso/e environment block address. 

Return Codes in Register 15 

Function was successful; the address of the evalblok was returned in evbptr. 
If an evalblok address was passed, the block was freed. 

8 Storage was insufficient to obtain the evalblok. If an address of an evalblok 
was passed, the storage was freed. 

12 An invalid request was made. One of the required parameters was not cor- 
rectly specified. 

20 Processing was not successful. A new evaluation block was not allocated 
(mvs/xa only). 

28 Processing was not successful. A valid language processor environment 
could not be located for the current task (mvs/xa only). 
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DSISSS - Search Span Name Table Services 

Macro dsisss determines whether an operator has authority to control a particular 
resource. 

dsisss checks a specified bit position in the span name table (snt) and returns the 
address of the first entry whose corresponding bit is set to 1. (See Figure 17.) The 
address is returned to a user-provided fullword area. 

mvt addressability is required. 



[name] DSISSS 



SWB = {(register)\symbolic name} 
.OITPOS — {(register)\symbolic name} 
.SNTADDR = {(register)\symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

OITPOS 

Register containing the address of a user-provided fullword area, or symbolic 
name of that area. This area should contain the bit position to be checked for 
the first bit set to 1 in the snt. 

Note: The bit positions in the snt correspond to entry positions in the operator 
identification table (orr); for example, the first bit corresponds to the first entry 
in theoiT. 

SNTADDR 

Register containing the address of a user-provided fullword area, or symbolic 
name of that area. On input, this area should contain the address of the entry 
in the snt where the search is to begin. When the routine has completed proc- 
essing, this area contains the address of the first entry that the search encount- 
ered whose corresponding operator bit was set to 1. The starting address 
specified in sntaddr may also be stored elsewhere in case relative location 
calculations are necessary for searching the authorization and routing table 

(ART). 

The span name table (snt) is illustrated below. 



Address where the 
search is to begin- 
specified by SNTADDR 
parameter on input 



Address of first 
entry whose bit is set 
to 1-found in 
SNTADDR on output 



DSISNT 



SPAN1 


010101010l'o'l011 


SPAN2 


111001011001100 


SPAN3 


001011001010010 


SPAN4 


001011011011011 






| SPANn 


0101011011PJ110 



Bit position to be 
checked-specified by 
the OITPOS parameter 

/ 



Figure 17. Span Name Table (SNT) 
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Return Codes in Register 15 

Function was successful; an entry was found and its address was returned. 

12 Unsuccessful. No entry was found. The address originally submitted is still 
in the area specified by sntaddr. 
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DSISYS - Operating System Indicator 



Macro dsisys is used for testing the current operating system. It is meant for use in 
programs that are to be run on multiple operating systems, to vary compilation 
according to the current system. It allows for system dependent code to be placed 
in common programs. 



DSISYS 



&DSISYST 

Global variable that must be declared. &dsisyst is set at compilation time by 
the dsisys macro to reflect the current operating system. Use the aif assem- 
bler statement to test its value. Possible values are: 



Value 


Operating System 


VS2/MVS 


MVS/370 


MVS/XA 


MVS/XA 


VM/SI 


VM/370 


DOS 


VSE 
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DSIWAT - ECB Wait Services 

Macro dsiwat causes a subtask to wait for completion of an event. 
MVT addressability is not required. 



[name] DSIWAT f ECB - {(register)\symbolic name} 1 
\ ECBLIST = {(register)\symbolic name} J 
[,DPR = {(reg/ster)|MVTDPRAD(,MVTPTR)}] 



ECB 

Register (2 — 12) containing the address of an aligned fullword to be used as 
an event control block (ecb), or symbolic name of that aligned fullword. 

ECBLIST 

Register containing the address of a contiguous list of fullword addresses of 
ecbs, or symbolic name of that list. The last entry in the list of ecb addresses 
has the high-order bit set to 1 to indicate the end of the list. 

DPR (required for NetView Release 2 vse only) 

In vm/sp and mvs, this parameter is ignored. However, if you want to write a 
routine to compile and run on both a NetView Release 2 vse system and on a 
NetView Release 3 mvs or vm/sp system, you will need to include this param- 
eter. In vse, this parameter specifies a register containing the address of the 
NetView dispatcher (dsidprnv), or mvtdprad(,mvtptr), where mvtptr is the sym- 
bolic name of a fullword area that contains the address of the mvt. 

The following example shows how dsiwat can be coded: 



DSIWAT ECBLIST=LISTAREA 



ECB1 


DC F'O* 


ECB2 


DC F'0' 


LISTAREA 


DC A(ECB1) 




DC A(ECB2) 




DC A(ECB3) 




DC A (ECB4+X' 80000000') 


ECB3 


DC F'0' 


ECB4 


DC F'0' 



Execution resumes when any one ecb is posted. The dsipos macro is used to set 
bit 1 of the ecb to 1. A completion code can also be set in the low-order three bytes 
of the ecb. 
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DSIWCS - Write Console Services 



Macro dsiwcs writes a message to the system operator's console. However, this 
macro should not be used to output a dbcs message, dbcs messages are not oper- 
ating system supported. 

The message will be truncated at 120 characters. The message buffer must have 
an initialized buffer header. 

mvt addressability is required. 



[name] DSIWCS SWB = {(register) {symbolic name} 
,BFR = {(register)\symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

BFR 

Register, or symbolic name of a fullword area, containing the address of a 
buffer with the message. This buffer must have an initialized bufhdr. 

Return Code in Register 15 

Function was successful; the message was sent to the system console. 
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DSIWLS - Write Log Services 



Macro dsiwls writes a record to the network log, the hard-copy log, the mvs system 
log, an external log, or a NetView sequential log depending on the use of the 
defaults command, the override command, dsiexo2A, or dsiexo4 as follows: 

• Without the extlog parameter, dsiwls can send records to the network log, the 
mvs system log, the operator's hard copy device or with the samrec parameter, 
to a NetView sequential log. For the network log, the record may be truncated, 
depending on the user-defined vsam record size. For the mvs system log, 
system truncation rules apply. 



• 



With the extlog parameter, dsiwls sends records to an external task that can 
log the data. 



mvt addressability is required. 



[name] DSIWLS SWB = {{register) [symbolic name} 
' ,BFR = {(register)\symbolic name] 



[f ,HCT= {{register)\symbolic name} 1 "| 

\, EXTLOG = 'xxx* \{register)\symbolic name}jj 
.SAMREC = {(reg/ster)|symbo//c name} 

,SAMLEN = {(register)\symbolic name} 
.SAMTASK = {(register)\symbolic name} 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). 

BFR 

Register, or symbolic name of a fullword area, containing the address of a 
user-provided input buffer. This buffer should contain the record that is to be 
logged. This buffer must have an initialized bufhdr. 

Note: You must specify either bfr or samrec, but not both. 

HCT 

Register, or symbolic name of a fullword area, containing the hard copy task's 
tvb address. 

Note: You may specify either hct or extlog with bfr, but not both. 

EXTLOG 

Indicates that the buffer is to be logged externally under the dsieltsk subtask. 
See NetView Installation and Administration Guide. 

External logging can be accomplished in one of the following ways: 

• Write to an smf data set. This option is restricted to mvs systems. The data 
to be logged must be a standard System Management Facilities (smf) 
record, with an smf record type greater than or equal to 128. The dstxitxl 
user exit is called prior to writing the record to smf. 

• Write to a data set other than smf. This option is not restricted to any par- 
ticular operating system. The user must code and install the dst xitxl user 
exit. This user exit then performs the actual logging. 

Note: You may specify either extlog or hct with bfr, but not both. 
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XXX 

Three characters that become the last three characters of the command 
name used to select the command processor that will log the data. The 
first characters of the verb must begin with dsiel. For example, if 
extlog= 'ABC, the cmdmdl statement in dsicmd must be: 



DSIELABC CMDMDL MOD=DSIELSMF,TYPE=D 



Register 

Register that contains the address of a 3-byte area that represents the last 
three letters in the name of an external logging command processor. 

Symbolic name 

Symbolic name of a 3-byte area that represents the last three letters in the 
name of an external logging command processor. 

SAMREC 

A keyword that either points to or names the record that should be written to 
the NetView sequential log which is controlled by the task indicated by the 
samtask keyword. Unlike the bfr keyword, this parameter should only point to 
the data that is to be logged. NetView services will put the record into the 
correct format for scheduling the record to the sequential log task. 

Note: You must specify either bfr or samrec, but not both. 

SAMLEN 

Register, or symbolic name of a fullword area, containing the length of the 
record to be logged. If the value of samlen is greater than 32,000, the record to 
be logged will be truncated and the macro will return a non-zero return code. 

The blksize for a sequential logging task must be at least as large as samlen 
plus 36 or the record to be logged will be truncated, samlen is required with 

SAMREC. 

SAMTASK 

Register, or symbolic name of a 2 fullword area, containing the name of the 
NetView task that has been defined to do sequential logging. This task will be 
verified for sequential logging capability, samtask is required with samrec. 



Return Codes in Register 15 

If extlog and samrec are not specified: 



Function was successful; the record has been sent to the network log and to 
the hard-copy log. 

4 No storage is available for logging. 

8 Successful log to the hard-copy log; network log not active. 

12 Successful log to the network log; hard-copy log not active for this task. 

16 The hard-copy log for this task and this network log are both inactive. 

If samrec is specified: 

Function was successful; the record has been queued to the sequential log 
task. 

4 No storage is available. 
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16 The task is not active, no data set is available, or the specified task is not a 
sequential log task. 

// extlog is specified: 

Function was successful. A copy of the caller's buffer has been queued to the 
external logging task (dsieltsk). 

4 No storage is available for copying the user input buffer for logging. 

24 No external logging command processor was found. 

28 dsimqs failed attempting to send the log record to the external logging task. 
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Macro dsizcsms is a data services macro. It requests and sends cnm data over the 
cnm interface. 

dsizcsms embeds the caller's network services request/response unit (ru) in a 
Forward ru that is passed to the sscp over the access method's cnm interface. The 
sscp then sends the embedded ru to the specified destination. For more informa- 
tion about sna's rus, see Systems Network Architecture Formats. 

mvt addressability is not required. 



{name'] DSIZCSMS SWB = {(reg/ster)|symDo//cname} 
,DSRB = {{register)\symboiic name} 
.INPUT = {(register)\symbolic name} 
.LENGTH = {(register)\symbolic name} 
,RU = {(register) \ symbolic name} 
.RULENG = {(register)\symbolic name} 
,DEST= {(register)\symbofic name} 
[.OPTION = {NOCNM|NOPRID|SALT}3 
[.TYPE = {CHAIN|RU|NOEMBED}] 
[,RTYPE= {REPLYJ RESPONSE}] 
.TARGET = {(register)\symbolic name} 
[.SECONDS = {(register)\symbotic name}] 



Note: swb, dsrb, and at least one other parameter are required. 

SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb) to be passed to the cnm interface service routine 

DSIZCSMM. 

DSRB 

Register, or symbolic name of a fullword area, containing the address of a data 
services request block (dsrb) to be passed to the cnm interface service routine 

DSIZCSMM. 

INPUT 

Register, or symbolic name of a fullword storage location, containing the 
address of a user input buffer. The size of the input buffer must be large 
enough to contain a 24-byte buffer header plus the length of the ru to be sent (if 
a Forward ru is to be built add an additional 28 bytes to the size of the input 
buffer). This buffer must contain a buffer header followed by text; it also holds 
the Deliver ru that is returned by the access method. To enable command 
processors or user exit routines that operate in 24-bit addressing mode to 
access the buffer, it must reside below 16 Mb. To receive a reply over the cnm 
interface, the buffer must accommodate at least a 32-byte reply (a 24-byte 
NetView buffer header and an eight-byte positive or negative response). 

LENGTH 

Register, or symbolic name of a fullword storage location, containing the 



length in binary of the input buffer. 
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RU 

Register, or symbolic name of a fullword storage location, containing the 
address of a user area. The area is an ru that is to be embedded within the 
Forward ru. 

RULENG 

Register, or symbolic name of a fullword user area, containing the length in 
binary of the embedded ru buffer. The ruleng may not exceed 32743 decimal 
bytes. 

DEST 

Register, or symbolic name of a fullword user area, containing the address of 
the network destination to which the embedded ru is sent. This network desti- 
nation must be eight characters long, left-justified, and padded with blanks if 
necessary. 

Note: You may specify either option or type, but not both. 

OPTION 

Allows nonstandard Forward rus to be sent by cnm interface services. 

NOCNM 

Indicates that a Forward ru will be sent that does not contain a cnm 
header, or procedure-related id (prid). An example is a forward ru con- 
taining ns ipl command types of init, text, and final. 

Note: For rtype = reply, you may specify either option =nocnm or seconds, 
but not both. 

NOPRID 

Indicates that a Forward ru will be sent that does not contain a procedure- 
related id (prid) in the cnm header. An example is a reqms that does not 
require a reply recfms because of user protocols. 

Note: For rtype= reply, you may specify either option = noprid or seconds, 
but not both. 

SALT 

Indicates that a Forward ru will be sent that is associated with a target. 
This flag alerts vtam that a target to the sna address list translation is 
required for an nmvt to be transported using a Forward ru. 

TYPE 

Controls the processing for the ru. 

CHAIN 

Indicates that the dsrb has received data and should remain in use to 
accept further rus associated with the specific request. If type= chain is 
specified, the swb and dsrb parameters are required; all other operands 
are invalid. This parameter is invalid with an unsolicited dsrb. 

Note: You may specify either type = chain or seconds, but not both. 

RU 

Indicates that the input ru is not to be embedded in a Forward ru. 

Note: You may specify either type=ru or seconds, but not both. 

NOEMBED 

Indicates that a Forward ru is not to be built for this request. 

RTYPE 

Describes the response required for the request. 
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REPLY 

Indicates that a Reply ru is required for completion of the request. 

Note: You may specify only one of the following: option = nocnm, 

OPTION = NOPRID, Or SECONDS. 

RESPONSE 

Indicates that a positive response is sufficient to complete the request. 

TARGET 

Register, or symbolic name of a fullword user area, containing the address of 
the network component that is the object of the embedded ru, or symbolic 
name of that network component. This network component must be eight char- 
acters long, left-justified, and padded with blanks if necessary. 

SECONDS 

Specifies the number of seconds to wait before cancelling the outstanding 
request. The number must have a positive value no greater than 86,400. If the 
seconds parameter is not specified or the value is zero, no timeout function is 
performed (an indefinite wait is possible). If you specify seconds, you cannot 
specify any of the following: type = ru, type=chain, option = nocnm, nor 
option =noprid. If seconds is specified and rtype= reply, then dest must be 
specified. 5 



1 . DSIZCSMS SWB = SWBADDR, DSRB = DSRBADDR, INPUT = RAQDDR, LENGTH = FORWDLEN, 

RU = READYRU, RULENG = READLEN, DEST = DESTNAME, RTYPE = REPLY, SECONDS = TIMEOUT. 

The data will be sent across the cnm interface to destname. readyru contains 
the request ru that is to be sent. The reply information is returned in the 
rqaddr buffer. After timeout seconds, the request will be cancelled. If an 
associated reply is received later, it will be discarded. 

2. DSIZCSMS SWB = SWBADDR, DSRB = DSRBADDR, INPUT - RAQDDR, LENGTH = FORWDLEN, 
RU = READYRU, RULENG = READLEN, DEST = DESTNAME, RTYPE = REPLY. 

The data will be sent across the cnm interface to destname. readyru contains 
the request ru that is to be sent. The reply information is returned in the 
rqaddr buffer. The request will remain outstanding until a reply is received. 



Return Codes in Register 15 

Major return codes in Register 15: 



Function was successful; data was sent to vtam. 

4 The requested function could not be performed. 

8 The input buffer was too small to build a Forward ru. 

12 An error was found in parameter specification. 

16 The program was not executing under a data services task. 

20 The ruleng exceeded the maximum ru length allowed. 

Minor return codes in Register 0: 

The function was successful. 



5 The seconds function is available only with vtam V3R1.1 or later. 
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4 The swb was invalid. 

8 The dsrb was invalid. 

12 The dsrb that was passed was in use. 

16 An unsolicited dsrb was passed. 

20 An invalid operator id was specified in the dsrb. 

24 Reserved. 

28 There was insufficient storage to process the request. 

32 The cnm interface is inactive. 

36 The request was rejected by the access method. 

40 A user exit rejected the request 

44 Data truncation occurred during the user exit processing. 

48 The specified seconds value was invalid. 

Note: For major return codes of 8 or 20, register will contain the ruleng. 



220 NetView Customization: Assembler 



DSIZVSMS 



DSIZVSMS - VSAM Data Services 



Macro dsizvsms is a data services macro. It requests vsam services for a data ser- 
vices command processor (dscp). 

dsizvsms provides access to vsam services that perform i/o to the specified problem 
determination file or data set. The parameters allow access for data recording, 
data retrieval, and data deletion. 

mvt addressability is not required. 



[name] DSIZVSMS SWB = {(register)\symbolic name} 
,DSRB= {(register)\symbolic name} 
,FUNC = {GET|PUT|POINT|ENDREQ|ERASE} 
[,KEY= {(register)\symbolic name}] 
[,KEYLEN = {(register) | symbolic name}] 
[.OPTION = ({SEQ|DIR|SKP},{ARD|LRD},{FWD| 

BWD},{NUP|NSP|UPD},{KEQ|KGE}, 

(FKSIGEN)}] 
[.DATAREA = {(register)\symbolic name}] 



SWB 

Register, or symbolic name of a fullword area, containing the address of a 
service work block (swb). The swb contains a save area, work area, and tib 
address data. The caller must initialize the swbtib field in the swb with a valid 
tib address. 

DSRB 

Register, or symbolic name of a fullword, containing the address of a data ser- 
vices request block (dsrb). The dsrb contains request information such as rpl, 
acb, ecb, and fields used by the dst vsam service routine for vsam i/o. 

FUNC 

Describes the vsam request macro to be issued. See OS/VS VSAM 
Programmer's Guide (for mvs) and Using VSE/VSAM Commands and Macros 
(for vm and vse only) for more information on how to specify func. 

KEY 

Register containing the address of the vsam key to be used for access to the 
requested data, or symbolic name of a fullword that contains the key. 

KEYLEN 

Register, or symbolic name of a fullword, containing the length in bytes of the 
key pointed to by key, or a symbolic name of a fullword with the length (in 
bytes) of the key. The default value is 1. 

OPTION 

Specifies the type of access to the file through requests defined by the NetView 
rpl. Options are arranged in groups. The first time the rpl is set up, you must 
specify one, and only one, option from each group. Subsequently, you may 
specify one option from one or more groups. You must separate multiple 
options with commas. 

This parameter has no defaults. This parameter is not valid when func= erase 
or func=endreq is specified. See OS/VS VSAM Programmer's Guide (for mvs) 
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and Using VSE/VSAM Commands and Macros (for vm and vse only) for more 
information on how to specify option. 

DATAREA 

Register containing the address of a user work buffer, or symbolic name of that 
buffer. The buffer must be large enough to contain the maximum size record in 
the file or data set and is used by vsam in the processing of records. This 
buffer must contain an initialized bufhdr, followed by text. For mvs/xa, if any 
command processors or user exits which operate in 24-bit addressing mode 
are to access the data area, the data area must reside below 16 Mb. 



Return Codes in Register 15 

Major return codes in Register 15: 

Successful completion of vsam function. 



4 Manipulative macro error occurred during processing. See the explanation of 
rpl feedback codes in OSIVS VSAM Programmer's Guide (for mvs) and Using 
VSE/VSAM Messages and Codes (for vm and vse only). 

8 An error occurred in the execute form of a manipulative macro. A parameter 
was not in the list. See the explanation of rpl feedback codes in OS/VS 
VSAM Programmer's Guide (for mvs) and Using VSE/VSAM Messages and 
Codes (for vm and vse only). 

12 Unsuccessful completion. 

16 dsizvsms was issued while not executing under a dst. 

Minor return codes in Register 0: 

Successful completion. 

4 The specified dsrb was invalid or in use. 

8 An acb was unavailable or was not open. 

12 Resume verb processing error. 

16 A user exit rejected the request. 

20 The vsam i/o request was invalid or there was an i/o scheduling error. 

24 Data truncation occurred during substitution of data in a user exit. Or, control 
block storage could not be obtained. 

28 A user exit returned an invalid return code. 
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Appendix A. Assembler Samples 



This appendix contains a table of the assembler samples that are shipped with 
NetView in syslcnmsamp. When data set names are referred to in this appendix, 
two names are given, such as atmpplt (CNMS4202). The first name is the alias name, 
and the name in parenthesis is the one in the NetView samples library. You can 
use either name to access the samples, dsicmd has definitions for the alias names 
to allow those names to be entered as commands. 

The following steps allow you to enter the member names as commands: 

1. Assemble and link-edit the samples using the alias name. 

2. Delete the asterisk (*) in column 1 of the appropriate cmdmdl statment in dsicmd 
to be able to execute the alias name as a command. No entries are needed in 
dsicmd for user exits. 

3. NetView must be recycled to pick up the dsicmd changes. 

Notes: 

1. See the prologues of the samples for information about how certain samples 
are related and special cases for user exit routines and other samples 

(DSIUSROO). 

2. The alias name is the same as the csect name. 

3. Each alias name for the assembler samples begins with the letter A, except for 
dsiusroo and dsiexo2a. 

This appendix also contains a description of each sample and coded samples of a 
user exit routine and a command processor. 
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Assembler Samples Table 



The following table refers to the assembler samples that are shipped with NetView. 
The table contains the function, the alias name, and the name of the member in 

SYS1.CNMSAMP. 

Sample function 



Template for assembler command processor 
Defines an XITVN DST exit to initialize an empty 

VSAM data set 
Uses DSIMDS to build a message module 
Uses DSIWLS to write a message to the NetView log 
Uses DSIPSS for title line output 
Uses DSIPSS to display date and time 
Logs text to a sequential log 
Lists a member of DSIPARM 
User written optional subtask 
Uses DSIMBS to build messages 
Uses DSIPSS to display a full screen panel 
Calls another command 
User defined message member 
Template for assembler user exit 
Uses DSIEX02A to manipulate messages 



Assembler 


sample 


Alias 


CNMSAMP 


ATMPCMDP 


CNMS42G2 


AXITVN 


CNMS4270 


AMSGMOD 


CNMS4271 


AWRTLOG 


CNMS4272 


AMLWTO 


CNMS4273 


ADATTIM 


CNMS4274 


ASEQLOG 


CNMS4275 


ALISTMEM 


CNMS4276 


AOPTTSK 


CNMS4277 


ABLDMSG 


CNMS4278 


APSSFULL 


CNMS4279 


ACALLCMD 


CNMS428G 


DSIUSRO0 


CNMS4281 


ATMPUXIT 


GNMS4282 


DSIEX02A 


CNMS4283 
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Assembler Samples Description 



For each sample, a description of the function and the NetView service macros uti- 
lized are given. 

ATMPCMDP (CNMS4202) 

This sample is a template for command processors in assembler. 

This sample is included in "Template for a Command Processor" on page 71. 

AXITVN (CNMS4270) 

This sample is an xitvn dst exit. It provides the initial record for an empty VSAM 
data set. 

NetView service macros utilized in this sample: dsicbs, dsidatim. 

AMSGMOD (CNMS4271) 

This sample uses the message definition services (DSimds) to build a user-defined 
message module (amsgmod). It is used in conjunction with the abldmsg sample 
command processor and DSIEX02A. 

NetView service macro utilized in this sample: dsimds. 

AWRTLOG (CNMS4272) 

This sample uses dsiwls to write a message to the NetView log. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsiwls. 

AMLWTO (CNMS4273) 

This sample uses dsipss for title-line output. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsipss. 

ADATTIM (CNMS4274) 

This sample uses dsipss to display date and time. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsipss. 

ASEQLOG (CNMS4275) 

This sample logs text to a sequential log. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsimqs, dsipss, 
dsiwls. 

This sample is included in "Sample Command Processor for Sequential Logging" 
on page 238. 

ALISTMEM (CNMS4276) 

This sample reads and displays a member from the NetView dsiparm data set. It 
also scope checks the supplied parm member name to prevent unauthorized 
display of dsiopf. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsidks, dsikvs, 
dsipss. 
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AOPTTSK (CNMS4277) 

This sample is an example of a user written optional subtask. 

This sample is included in "Template for an Optional Task" on page 95. 

ABLDMSG (CNMS4278) 

This sample uses dsimbs to build user defined messages. 

NetView service macros utilized in this sample: dsicbs, dsidatim, dsidel, dsilod, 

DSIMBS, DSIPSS. 

APSSFULL (CNMS4279) 

This sample uses dsipss to display a full screen panel, wait for terminal input, and 
echo the input. 

NetView service macros utilized in this sample: dsicbs, dsifre, dsiget, dsipss, 
dsiwat. 

ACALLCMD (CNMS4280) 

This sample calls another command. 

NetView service macros utilized in this sample: dsicbs, dsices, dsidatim, dsifre, 
dsiget, dsilcs, dsiprs. 

DSIUSROO (CNMS4281) 

This sample is an example of a user defined message member. It is used in con- 
junction with the abldmsg sample command processor. 

ATMPUXIT (CNMS4282) 

This sample is a template for assembler user exits. See "Template for a User Exit 
Routine" on page 48. 

DSIEX02A (CNMS4283) 

This sample is used to manipulate messages. The user exit is invoked for 
standard output to the operator's terminal. If DWO403I is the incoming message, it 
will mqs a start task request to start the task specified in DWO403I and swap the 
message buffer to indicate that the task has been started and that the request 
should be reissued. 

NetView service macros utilized in this sample: dsicbs, dsidel, dsifre, dsiget, dsilcs, 

DSILOD. DSIMBS, DSIMQS, DSIPRS. 

This sample is included in "Sample User Exit" on page 229. 
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Assembler Coded Samples 

This section contains an example of a user exit routine and a command processor. 



Sample User Exit 



This sample is an example of user exit dsiexoza. 

DSIEX02A CSECT 
********************************************************** 

* * 

* IEBCOPY SELECT MEMBER=((CNMS4283,DSIEX02A,R)) * 

* * 

* (C) COPYRIGHT IBM CORP. 1989 * 

* * 

* MODULE NAME: DSIEX02A * 

* * 

* FUNCTION: THIS USER EXIT IS INVOKED FOR STANDARD OUTPUT TO THE * 

* OPERATOR'S TERMINAL (DSIPSS TYPE=OUTPUT, IMMED OR FLASH). * 

* IF MESSAGE DW0403I IS THE INCOMING MESSAGE, IT WILL MQS * 

* A START TASK REQUEST TO START THE SPECIFIED OPTIONAL * 

* TASK AND SWAP THE MESSAGE BUFFER TO INDICATE THAT THE * 

* TASK HAS BEEN STARTED AND TO RE-ISSUE THE REQUEST. * 



* INSTALLATION: AMSGMOD MESSAGE TABLE (CNMS4271) MUST BE LINKED 

* INTO THE USER LIBRARY. 



************************************************************************ 

* INPUT: REG 1 - ADDRESS OF USER EXIT PARAMETER LIST (DSIUSE) * 

* REG13 - ADDRESS OF CALLER'S SAVE AREA * 

* REG14 - RETURN ADDRESS * 

* REG15 - ENTRY ADDRESS * 

* * 

* OUTPUT: * 

* * 

* OUTPUT: REGO - ADDRESS OF SWAPPED MESSAGE IF REG15 =8 * 

* * 

* REG15 - RETURN CODE * 

* = USE MESSAGE AS IS, DO NOT DELETE OR REPLACE * 

* 4 = DELETE MESSAGE FROM THE TERMINAL & THE LOG * 

* 8 = REPLACE MESSAGE WITH MESSAGE ADDRESSED IN REGO * 

* * 

* NETVIEW MACROS: * 

* * 

* DSICBS - CONTROL BLOCK SERVICE * 

* DSIDEL - DELETE USER-DEFINED MODULE * 

* DSIFRE - FREEMAIN STORAGE SERVICE * 

* DSIGET - GETMAIN STORAGE SERVICE * 

* DSILCS - LOCATE CONTROL BLOCK * 

* DSILOD - LOAD USER-DEFINED MODULE * 

* DSIMBS - MESSAGE BUILD SERVICE * 

* DSIMQS - MESSAGE QUEUEING SERVICE * 

* DSIPRS - PARSE DESCRIPTOR BLOCK * 
*********************************************************************** 

EJECT 

* 

*********************************************************************** 

* 

* INCLUDE THE REQUIRED CONTROL BLOCKS 
* 

*********************************************************************** 

* 

DSICBS DSITIB,DSITVB,DSIMVT,DSISVL,DSISWB, DSIUSE, DSIIFR, > 
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DSISVL,DSIPDB,PRINT=NO 




RO 


EQU 







Rl 


EQU 


1 




R2 


EQU 


2 




R3 


EQU 


3 




R4 


EQU 


4 




R5 


EQU 


5 




R6 


EQU 


6 




R7 


EQU 


7 


MVT 


R8 


EQU 


8 


TVB 


R9 


EQU 


9 


USE 


RIO 


EQU 


10 




Rll 


EQU 


11 




R12 


EQU 


12 


BASE REG 


R13 


EQU 


13 


SAVEAREA 


R14 


EQU 


14 




R15 


EQU 
EJECT 


15 





************************************************************** 

* * 

* DSIEX02: SET UP ENTRY LINKAGE * 

* * 

*********************************************************************** 
* 

DSIEX02A CSECT 

USING \R15 

B PROLOG 

DC CDSIEX02A &SYSDATE. AT &SYSTIME.' 

PROLOG DS OH 

STM R14,R12,12(R13) SAVE CALLER'S REGISTERS 

DROP R15 

LR R12.R15 SAVE BASE REGISTER 

USING DSIEX02A.R12 REG 12 IS THE BASE REG 

USING DSIUSE, Rl REG 1 POINTS TO DSIUSE 

L Rll.USERSWB LOAD REG 11 WITH SWB ADDRESS 

USING DSISWB.R11 BASE SWB 

LA R2.SWBSAVEA GET ADDRESS OF OUR SAVE AREA 

ST R2,8(,R13) SET CALLER'S FORWARD POINTER 

ST R13,4(,R2) SET OUR BACKWARD POINTER 

LR R13.R2 REG 13 CONTAINS SAVE AREA ADDR 

LR R9.R1 MOVE DSIUSE ADDRESS 

DROP Rl DROP ORIGINAL DSIUSE BASING 

USING DSIUSE, R9 REG 9 POINTS TO DSIUSE 

L R8.USERTVB LOAD REG 8 WITH TVB ADDRESS 

USING DSITVB.R8 BASE THE TVB 

L R7.TVBMVT LOAD REG 8 WITH TVB ADDRESS 

USING DSIMVT,R7 BASE THE MVT 

* 

*********************************************************************** 

* * 

* MESSAGE DW0403I IS NOT EXPECTED IN AN EXIT. CHECK TVBINXIT AND * 

* EXIT IF SET. * 

* * 
*********************************************************************** 
* 

TM TVBIND3, TVBINXIT IS TVBINXIT ON 

BO ASIS YES, LEAVE 

* 

*********************************************************************** 

* * 

* CHECK INPUT MESSAGE NUMBER AND EXIT IF IT IS NOT "DW0403I" * 

* * 

*********************************************************************** 



L R4.USERMSG LOAD REG 4 WITH INPUT AIFR 
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USING BUFHDR.R4 

L R2.USERMSG 

AH R2.HDRTDISP 

DROP R4 

USING DSIIFR.R2 

L R3.IFRAUTBA 

USING BUFHDR.R3 

L R4.IFRAUTBA 

AH R4.HDRTDISP LOCATE START OF TEXT 

CLC 0(7,R4),=CL7'DW0403r IS IT DW0403I 

BNE ASIS NO, EXIT 



BASE THE INPUT MESSAGE BUFFER 
GET ADDRESS OF AIFR 
LOCATE START OF TEXT 

BASE THE IFR 

LOAD REG 3 WITH ADDR INPUT MSG 



*********************************************************** 

* * 

* IF MSG DW0403I IS NOT A NETVIEW SINGLE LINE MESSAGE OR * 

* IS A COPY OF ANOTHER MESSAGE OR * 

* IS A MESSAGE FROM ANOTHER DOMAIN, THEN EXIT. * 

* * 

*********************************************************************** 



CLI 


HDRMTYPE.HDRTYPEN 


BNE 


ASIS 


TM 


IFRAUIN2.IFRAUSEC 


BO 


ASIS 


TM 


IFRAUIN2.IFRAUCPY 


60 


ASIS 


TM 


IFRAUIND.IFRAUXDM 


BO 


ASIS 


ST 


R3.INPUTMSG 


DROP 


R3 



NETVIEW SINGLE LINE MSG ?? 

NO, COULD BE "COMMAND" ECHO 

WAS IT ROUTED USING ASSIGN=SEC 

YES, LEAVE 

WAS IT ROUTED USING ASSIGN=CPY 

YES, LEAVE 

IS IT FROM ANOTHER DOMAIN 

YES, LEAVE 

SAVE ADDR OF INPUT MESSAGE 



*********************************************************************** 

* * 

* INITIALIZE ALL POINTERS TO ZERO * 

* * 

*********************************************************************** 



SR R4.R4 

ST R4.MSGBFR 

ST R4.ADDRSWB 

ST R4.ADDRPDB 

ST R4.MSGTABLE 

MVC TASKID.-8C ' 



INIT MSG BUFFER POINTER 

INIT SWB POINTER 

INIT PDB POINTER 

INIT MSG TABLE POINTER 

INIT TASK ID FIELD 



*********************************************************************** 



GET A BUFFER FOR ISSUING/SWAPPING MESSAGES 



*********************************************************************** 



LA R4.BFRLENG 
DSIGET LV=(R4), 

A=MSGBFR, 

Q=NO, 

TASKA=(R8), 

SP=0 
LTR R15,R15 
BNZ ASIS 
L R3.MSGBFR 
USING BUFHDR.R3 
STH R4.HDRBLENG 
DROP R3 



GET LENGTH OF MSG BUFFER 



CHECK IF DSIGET SUCCESSFUL 
DSIGET UNSUCCESSFUL 



SET HDRBLENG IN BUFFER 



*********************************************************************** 



* LOAD THE USER MESSAGE TABLE 
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************************************************************* 
• 

DSILOD EP=AMSGMOD LOAD THE MESSAGE TABLE 

LTR R15.R15 WAS DSILOD SUCCESSFUL 

BNZ LODFAIL NO, EXIT 

ST RO.MSGTABLE 
* 

*********************************************************************** 

* * 

* GET ANOTHER SWB IN ORDER TO ISSUE NETVIEW SERVICE MACROS * 

* * 

*********************************************************************** 
* 

DSILCS CBADDR=ADDRSWB, X 

SWB=GET GET A NEW SWB 

LTR R15.R15 TEST DSILCS RETURN CODE 

BNZ NOSWB NOTIFY USER AND EXIT 

L R5.ADDRSWB PUT THE NEW SWB ADDR IN REG 5 

L R4.TVBTIB PUT THE TIB ADDR IN REG 4 

ST R4,SWBTIB-DSISWB(,R5) STORE TIB ADDR IN THE NEW SWB 
* 

*********************************************************************** 

* * 

* ISSUE DSIPRS TO DETERMINE THE SIZE OF THE PARSE TABLE REQUIRED TO * 

* PARSE THE INPUT BUFFER. * 

* * 

*********************************************************************** 
* 

DSIPRS SWB=ADDRSWB, X 

BFR=INPUTMSG, X 

PDBSIZE-SIZEPDB 
LTR R15.R15 WAS DSIPRS SUCCESSFUL 

BZ GETPDB YES, CONTINUE 

MVC REQUESTERS NO, SET MACRO NAME 

B MACFAIL NOTIFY USER AND EXIT 

SPACE 

* 

*********************************************************************** 

* * 

* ISSUE DSIGET TO GET STORAGE FOR THE PARSE TABLE * 

* * 

*********************************************************************** 
* 

GETPDB EQU * 

L R4.SIZEPDB GET TABLE SIZE 

DSIGET LV=(R4), X 

A=ADDRPDB, X 

Q=YES, X 

TASKA=(R8), X 

SP=0 

LTR R15.R15 CHECK IF DSIGET SUCCESSFUL 

BZ INITBFR DSIGET SUCCESSFUL 

SR R2.R2 

ST R2.INPUTMSG ZERO POINTER TO INPUT MSG 

BAL R6.FREESTOR FREE THE STORAGE AND EXIT 

B ASIS 

* 

*********************************************************************** 

* * 

* INITIALIZE THE CONTROL BLOCK HEADER IN THE PARSE TABLE * 

* * 

*********************************************************************** 
* 

INITBFR EQU * 

L R5.ADDRPDB ADDRESS OF THE PARSE TABLE 
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USING DSICBH.R5 

STH R4.CBHLENG 

MVI CBHID.CBHPDB 

DROP R5 



ADDRESSABILITY TO PARSE TABLE 
SET THE CONTROL BLOCK LENGTH 
SET THE CONTROL BLOCK ID = PDB 



EJECT 



*********************************************************************** 



* PARSE THE INPUT MESSAGE 



*********************************************************************** 



L R2.ADDRPDB 


GET PARSE TABLE ADDRESS 




DSIPRS SWB=ADDRSWB, 




X 


BFR=INPUTMSG, 




X 


PDB=(R2) 






LTR R15.R15 


CHECK IF DSIPRS SUCCESSFUL 




BZ GETNTRY 


YES, CONTINUE 




MVC REQUESTERS 


NO, SET MACRO NAME 




B MACFAIL 


NOTIFY USER AND EXIT 




EJECT 







*********************************************************************** 

* * 

* FIND PDBENTRY THAT CONTAINS THE TASK NAME. * 

* * 

*********************************************************************** 



GETNTRY EQU 
L 



LOOP1 



SET FOR ENTRY NUMBER OF TASKID 
GET ADDR OF 1ST ENTRY 



R5.ADDRPDB 

USING DSIPDB.R5 

LA R3.2 

LA R2.PDBTABLE 

USING PDBENTRY, R2 

DROP R5 

EQU * 

LA R2,PDBENTND-PDBENTRY(,R2) GET NEXT ENTRY 

BCT R3.LOOP1 



*********************************************************************** 



BUILD IFRCODE 3 AND MQS TO START THE TASK 



*********************************************************************** 



L 


R4.MSGBFR 


USING 


BUFHDR.R4 


LA 


R6.HDRMSGLN 


STH 


R6.HDRTDISP 


MVC 


HDRD0MID(8),MVTCURAI 


MVC 


HDRSENDR(8),TVB0PID 


MVI 


HDRMTYPE.HDRTYPEI 


L 


R5,MSGBFR 


AH 


R5.HDRTDISP 


USING 


DSIIFR.R5 


LA 


R6.IFRC0DCR 


STH 


R6, IFRCODE 


L 


R3.INPUTMSG 


AH 


R3.PDBDISP 


SR 


RIO, RIO 


I CM 


RIO.B'OOOl'.PDBLENG 


ST 


RIO.LTASKID 


BCTR 


R10.0 


EX 


R10.MOVE1 


MVC 


IFRPARMS(L'CMD),CMD 



LOAD REG 4 WITH MSG BFR ADDR 

BASE THE MESSAGE BUFFER 

LOAD REG 4 WITH OFFSET TO TEXT 

SET HDRTDISP 

SET DOMAIN ID 

SET SENDER ID 

MSG TYPE IS IFR 

GET ADDRESS OF MSG BUFFER 

GET ADDRESSABILITY TO IFR 



SET BUFFER AS A COMMAND 
GET INPUT MESSAGE 
LOCATE THE TASK NAME 

GET LENGTH OF TASK NAME 
SET LENGTH OF TASK NAME 
DECREMENT LENGTH FOR MOVE 
GET TASK NAME FROM INPUT BFR 
SET COMMAND 
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EX 


R10.M0VE2 


SET TASK NAME IN MSG BFR 




LA 


RIO, 1(, RIO) 


INCREMENT FOR ACTUAL LENGTH 




LA 


R6.IFRPARMS-DSIIFR 


LOAD REG 4 WITH LENGTH OF IFR 




LA 


R6,L'CMD(,R6) 


ADD LENGTH OF COMMAND 




LA 


R6,0(R10,R6) 


ADD LENGTH OF TASK NAME 




STH 


R6, HDRMLENG 


SET HDRMLENG 




DSIMQS TASKID=TVBOPID, 


X 






BFR=(R4), 


X 






SWB=ADDRSWB 


SEND TO OPER 




LTR 


R15.R15 


WAS DSIMQS SUCCESSFUL 




BZ 


STARTED 


YES, CONTINUE 




MVC 


REQUEST, MQS 


NO, SET MACRO NAME 




B 


MACFAIL 


NOTIFY USER AND EXIT 




SPACE 






M0VE1 


MVC 


TASKID(0),O(R3) 


GET THE TASK NAME 


M0VE2 


MVC 


IFRPARMS+L'CMD(0), 


TASKID SET TASK NAME 




DROP 


R2.R5 






EJECT 







*************************************************************** 

* * 

* STARTED: SWAP THE TEXT IN MESSAGE BUFFER TO INDICATE THAT WE * 

* HAVE STARTED THE TASK AND TO RETRY THE REQUEST. * 

* * 

*********************************************************************** 
* 

STARTED EQU * 

L R3.INPUTMSG GET INPUT MESSAGE 

MVC HDRMLENG(HDRMSGLN),0(R3) SET THE MESSAGE LENGTH 

MVI HDRMTYPE.HDRTYPEU SET MSG TYPE TO USER 

LA R2.BFRLENG 

STH R2.HDRBLENG SET THE BUFFER LENGTH 

DSIMBS SWB=ADDRSWB, X 

MID=004, X 

BFR=(R4), X 

MSGTBL=MSGTABLE, X 

Pl= (TASKID, LTASKID) BUILD MSG004I 

DROP R4 

B SWAP 
* 

*********************************************************************** 

* * 

* NOSWB: TO SWAP INPUT MESSAGE FOR "NO SWB" MESSAGE * 

* * 

*********************************************************************** 
* 

NOSWB EQU * 

L R4.MSGBFR LOAD REG 4 WITH MESSAGE BFR ADDR 

USING BUFHDR.R4 BASE THE MESSAGE BUFFER 

L R3.INPUTMSG GET THE INPUT MSG ADDRESS 

MVC HDRMLENG(HDRMSGLN),0(R3) COPY INPUT BUFHDR TO MSG BFR 

MVI HDRMTYPE.HDRTYPEU MSG TYPE IS USER 

LA R2.BFRLENG 

STH R2,HDRBLENG SET THE BUFFER LENGTH 

LA R2,L'SWBMSG 

STH R2, HDRMLENG SET THE MESSAGE LENGTH 

L R2.MSGBFR GET ADDRESS OF MESSAGE BFR 

AH R2,HDRTDISP LOCATE START OF TEXT 

MVC 0(L'SWBMSG,R2),SWBMSG PUT MESSASGE IN BUFFER 

DROP R4 

B SWAP 

SPACE 

* 

*********************************************************************** 

* * 

* FREESTOR: TO FREE ALL STORAGE GOTTEN * 
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*********************************************************************** 



FREESTOR EQU 


4c 




L 


R2,ADDRSWB 




LTR 


R2.R2 




BZ 


CK4NPUT 




DSILCS CBADDR=ADDRSWB 






SWB=FREE 


CK4NPUT 


EQU 


* 




L 


R3,INPUTMSG 




LTR 


R3.R3 




BZ 


CK4PDB 




USING 


BUFHDR.R3 




LH 


R2.HDRBLENG 




DROP 


R3 




DSIFRE A=INPUTMSG, 






LV=(R2), 






Q=NO, 






SP=0 


CK4PDB 


EQU 


* 




L 


R2.ADDRPDB 




LTR 


R2.R2 




BZ 


CK4MSGM 




L 


R2.SIZEPDB 




DSIFRE A=ADDRPDB, 






TASKA=(R8), 






Q=YES, 






SP=0 


CK4MSGM 


EQU 


* 




L 


R2.MSGTABLE 




LTR 


R2,R2 




BZ 


XITFREE 




DSIDEL EP=AMSGMOD 


XITFREE 


EQU 


* 




BR 


R6 



GET SWB POINTER 
IS THERE AN SWB 
NO, CHECK FOR INPUT MSG BFR 

FREE THE SWB 

GET THE INPUT MSG POINTER 
DOES IT NEED FREEING 
NO, CHECK FOR A PDB 

GET LENGTH OF INPUT MSG BUFFER 



FREE THE INPUT MSG BUFFER 

GET THE PDB POINTER 

IS THERE ONE TO FREE 

NO, CHECK FOR A MESSAGE TABLE 

GET THE SIZE OF THE PDB 



FREE THE PDB 

GET THE MESSAGE TABLE POINTER 

IS THERE ONE TO FREE 

NO, RETURN TO CALLER 

YES, DELETE THE MESSAGE TABLE 

RETURN TO CALLER 



*************** ******************************************************** 

* * 

* MACFAIL: TO SWAP INPUT MSG TO INDICATE DSIPRS/DSIMQS FAILED * 

* * 

*********************************************** 



MACFAIL EQU * 

L R4.MSGBFR LOAD REG 4 WITH MESSAGE BFR ADDR 

USING BUFHDR.R4 BASE THE MESSAGE BUFFER 

L R3.INPUTMSG GET THE INPUT MESSAGE BUFFER 

MVC HDRMLENG(HDRMSGLN),0(R3) COPY INPUT BUFHDR TO MSG BFR 

MVI HDRMTYPE.HDRTYPEU SET MSG TYPE TO USER 



LA R2.BFRLENG 
STH R2.HDRBLENG 
DSIMBS SWB=ADDRSWB, 

MID=005, 

BFR=(R4), 

P1=(REQUEST,6), 

MSGTBL=MSGTABLE 
DROP R4 
B SWAP 
SPACE 



GET THE MSG BUFFER LENGTH 
SET MSG BFR LENGTH IN MSG BFR 



BUILD MSG005I 



*********************************************************************** 

* * 

* LODFAIL: TO SWAP INPUT MSG TO INDICATE DSILOD FAILED * 

* * 

*********************************************************************** 
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EQU 


* 


L 


R4.MSGBFR 


USING 


BUFHDR.R4 


L 


R3.INPUTMSG 


MVC 


HDRMLENG(HDRMSGLN 


MVI 


HDRMTYPE.HDRTYPEU 


LA 


R2.BFRLENG 


STH 


R2.HDRBLENG 


LA 


R2,L'L0DMSG 


STH 


R2.HDRMLENG 


L 


R2.MSGBFR 


AH 


R2.HDRTDISP 


MVC 


0(L'L0DMSG,R2),L0I 


DROP 


R4 


B 


SWAP 


SPACE 




EJECT 





LOAD REG 4 WITH MESSAGE BFR ADDR 
BASE THE MESSAGE BUFFER 
GET INPUT MESSAGE BUFFER ADDRESS 
J) SET MSG LENGTH IN MSG BUFFER 
SET MSG TYPE TO USER 
GET THE MSG BUFFER LENGTH 
SET THE MSG BUFFER LENGTH 
GET MESSAGE LENGTH 
SET MSG LENGTH IN MSG BUFFER 
GET ADDRESS OF MESSAGE BFR 
LOCATE START OF TEXT 



*********************************************************************** 

* * 

* ASIS: TO PROCESS THE BUFFER AS IT IS AND RETURN * 

* * 

********************************************************** 



ASIS 



EQU 


* 


LA 


R15.USERASIS 


L 


R13,4(,R13) 


L 


R14,12(,R13) 


LM 


R0,R12,20(R13) 


BR 


R14 


SPACE 





SET AN ASIS RETURN CODE 
RESTORE CALLER'S SAVE AREA ADDR 
RESTORE CALLER'S REG 14 
RESTORE CALLER'S REGS 0-12 
RETURN TO CALLER 



*********************************************************************** 

* * 

* SWAP: TO SWAP A BUFFER FOR THE INPUT BUFFER AND RETURN * 

* * 

*********************************************************************** 



SWAP EQU * 

L R4.USERMSG 
USING BUFHDR.R4 
L R2.USERMSG 
AH R2.HDRTDISP 
USING DSIIFR.R2 



L 


R3.MSGBFR 


ST 


R3.IFRAUTBA 


ST 


R3.IFRAUTBL 


DROP 


R2.R4 


BAL 


R6.FREEST0R 


LA 


R15.USERSWAP 


L 


RO.USERMSG 


L 


R13,4(,R13) 


L 


R14,12(,R13) 


LM 


R1,R12,24(R13) 


BR 


R14 


SPACE 




EJECT 




LTORG 
* 




******************************* 


* CONSTANTS 




******************************* 


CMD DC 


C START TASK*' 


PRS DC 


C'DSIPRS' 



GET ADDRESS OF AIFR 

GET ADDRESS OF AIFR 
LOCATE START OF TEXT 

GET ADDRESS OF MSG BUFFER 

PUT NEW MSG IN AIFR 

SET LAST MSG OF AIFR CHAIN 

FREE THE STORAGE 

SET A SWAP RETURN CODE 

LOAD REG WITH ADDR OF IFRCODAI 

RESTORE CALLER'S SAVE AREA ADDR 

RESTORE CALLER'S REG 14 

RESTORE CALLER'S REGS 1-12 

RETURN TO CALLER 



START COMMAND 
PARSE MACRO 
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MQS DC C'DSIMQS' MQS MACRO 

LODMSG DC C REQUEST CANNOT BE HONORED. LOAD FAILURE FOR AMSGMOD' 

SWBMSG DC C REQUEST CANNOT BE HONORED. UNABLE TO OBTAIN AN SWB' 

* 

********************************************************** 

* DECLARES AND DSECTS * 

*********************************************************************** 



DSISWB DSECT , 

ORG SWBADATD 
A 
A 
A 
A 
A 
F 
F 

CL6 
CL8 
100 
XL(256-(*-SWBADATD)) 



ADDRSWB DS 
MSGBFR DS 
ADDRPDB DS 
MSGTABLE DS 
INPUTMSG DS 
SIZEPDB DS 
LTASKID DS 
REQUEST DS 
TASKID DS 
BFRLENG EQU 

DS 

SPACE 
DSIEX02A CSECT , 

END DSIEX02A 



EXTEND THE SWB DEFINITION 

POINT TO THE 256 BYTE WORK AREA 

ADDRESS OF SWB 

ADDRESS OF MESSAGE BUFFER 

ADDRESS OF PDB 

ADDRESS OF MESSAGE TABLE 

ADDRESS OF INPUT MESSAGE BUFFER 

LENGTH OF PDB TO OBTAIN 

LENGTH OF TASK NAME 

LENGTH OF PDB TO OBTAIN 

TASK NAME 

LENGTH OF MESSAGE BUFFER 

ENSURE AUTODATA <= 256 BYTES 

RESUME CSECT 
END OF USER EXIT 
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Sample Command Processor for Sequential Logging 

This sample is an example of a command processor to log text to a sequential log. 

TITLE 'ASEQLOG - WRITE TO A SEQUENTIAL LOG" 
*********************************************************************** 

* * 

* IEBCOPY SELECT MEMBER=((CNMS4275, ASEQLOG, R)) * 

* * 

* (C) COPYRIGHT IBM CORP. 1989 * 

* * 

* * 

* MODULE NAME: ASEQLOG * 

* * 

* FUNCTION = THIS IS A COMMAND PROCESSOR FOR LOGGING * 

* TEXT TO A SEQUENTIAL LOG * 

* * 

********************************************************** 

* * 

* SYNTAX ASEQLOG TEXT-TO-LOG * 

* * 

*********************************************************************** 

* * 

* INSTALLATION: * 

* * 

* (1) ASSEMBLE AND LINKEDIT THIS MODULE AM00E-31.RM0DE-ANY * 

* TYPE=RENT * 

* (2) ALLOC PRIMARY AND SECONDARY SEQUENTIAL DATA SET * 

* (3) USE DD NAMES IN NETVIEW PROC OR THE ALLOCATE COMMAND * 

* TO ALLOCATE THE DATA SETS TO NETVIEW. * 

* ALLOCATE THE DATA SETS AS * 

* SQLOGP & SQLOGS * 

* (4) ADD THE FOLLOWING STATEMENT TO DSIDMN * 

* TASK MOD=DSIZDST,TSKID=SQL0GTSK,MEM=SQL0GMEM,PRI=3,INIT=Y * 

* (5) ADD THE FOLLOWING MEMBER (SQLOGMEM) TO DSIPARM * 

* DSTINIT FUNCT=OTHER,DSRBO=l * 

* DSTINIT PBSDN=SQLOGP * 

* DSTINIT SBSDN=SQLOGS * 

* LOGINIT AUTOFLIP=YES,RESUME=NO * 

* (6) ADD THE FOLLOWING CMDMDL TO DSICMD * 

* ASEQLOG CMDMDL MOD=ASEQLOG,TYPE=R,RES=N * 

* * 

* * 
*********************************************************************** 

* * 

* INPUT: * 

* REGISTERS: * 

* Rl = DSICWB ADDRESS * 

* R13 = ADDRESS OF STANDARD SAVEAREA * 

* R14 = RETURN ADDRESS * 

* R15 = ENTRY POINT OF ROUTINE * 

* * 

* * 

* OUTPUT: * 

* REGISTERS: * 

* RO - R14 = RESTORED UPON RETURN * 

* * 

* R15 = RETURN CODE - IF ALL GOES WELL. 4 IF SOME * 

* KIND OF FAILURE (STORAGE REQUEST OR MESSAGE * 

* QUEUING) OCCURS. * 



* NETVIEW MACROS: 
* 

* DSICBS - CONTROL BLOCK SERVICE 

* DSIMQS - MESSAGE QUEUEING SERVICE 
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DSIPSS - PRESENTATION SERVICES 
DSIWLS - WRITE TO LOG SERVICE 



***************************************************************** 

EJECT 

ASEQLOG CSECT 

DSICBS DSITIB,DSITVB,DSIMVT,DSISVL,DSISWB,DSICWB,DSIPDB,PRINT=X 

NO 
*********************************************************************** 

* MODULE ADDRESSABILITY IS ESTABLISHED * 

* CALLER'S REGS ARE SAVED * 
*********************************************************************** 



USING \R15 



ENTLINK 



B 


ENTLINK 


DC 


CL8' ASEQLOG' 


DC 


C'&SYSDATE' 


DS 


OH 


STM 


R14,R12,12(R13) 


LR 


R12.R15 


DROP 


R15 



SAVE CALLERS REGS 



LR 


R11.R13 


LA 


R13.CWBSAVEA 


XC 


8(4,R13),8(R13) 


ST 


R13,8(R11) 


ST 


R11,4(R13) 


SLR 


R15.R15 



USING ASEQLOG, R12 
*********************************************************************** 

* SET UP ADDRESSABILITY TO REQUIRED CONTROL BLOCKS. * 
*********************************************************************** 

USING DSICWB.R2 SET UP CWB ADDRESSABILITY 

USING DSITVB.R3 SET UP TVB ADDRESSABILITY 

USING DSITIB.R4 SET UP TIB ADDRESSABILITY 

USING DSIMVT.R5 SET UP MVT ADDRESSABILITY 

LR R2.R1 PUT ADDRESS OF CWB IN ITS BASE REG. 

L R4.CWBTIB PUT ADDRESS OF TIB IN ITS BASE REG. 

L R3.TIBTVB PUT ADDRESS OF TVB IN ITS BASE REG. 

L R5.TVBMVT PUT ADDRESS OF MVT IN ITS BASE REG. 
*********************************************************************** 

* CHAIN SAVE AREAS. * 
*********************************************************************** 

MOVE ADDRESS OF CALLER SAVEAREA 

PUT SAVEAREA AREA ADDRESS IN REG 13 

CLEAR MY FORWARD POINTER 

SET CALLERS FORWARD POINTER 

SET MY BACKWARD POINTER 

INITIALLY, RETURN CODE IS ZERO 

XC CWBADATD ( L ' CWBADATD) , CWBADATD CLEAR AUTODATA AREA 
*********************************************************************** 

* INITIALIZE BUFFER THAT IS TO BE USED FOR MESSAGES. * 

* MESSAGE LENGTH (HDRMLENG) will be set when the message to be sent * 

* HAS BEEN DETERMINED. * 
*********************************************************************** 

LA R6.MSGBFR ADDRESS MESSAGE BUFFER 

LA R7,L'MSGBFR LENGTH OF MESSAGE BUFFER 

STH R7,HDRBLENG-BUFHDR(R6) PUT BUFFER LENGTH IN HEADER 

LA R7.BUFHDRND-BUFHDR LENGTH OF HEADER (W/O EXTENSION) 

STH R7,HDRTDISP-BUFHDR(R6) STORE DISPLACEMENT TO TEXT AREA 

MVC HDRDOMID-BUFHDR(L'HDRDOMID,R6),MVTCURAN DOMAIN ID 

MVI HDRMTYPE-BUFHDR(R6),HDRTYPEU USER MESSAGE TYPE 
*********************************************************************** 

* CHECK RUNNING ENVIRONMENT. ENSURE THAT THE COMMAND ENVIRONMENT * 

* IS OST, PPT, OR NNT. THIS WAY, THE PDB THAT WE EXPECT WILL EXIST. * 
*********************************************************************** 

CLI CBHTYPE-DSICBH(R3),CBHOST CHECK FOR OST 

BE ENVIROK ENVIRONMENT OKAY IF OST 

CLI CBHTYPE-DSICBH(R3),CBHNNT CHECK FOR NNT 

BE ENVIROK ENVIRONMENT OKAY IF NNT 

CLI CBHTYPE-DSICBH(R3),CBHPPT CHECK FOR NNT 

BE ENVIROK ENVIRONMENT OKAY IF PPT 

* SET UP INVALID TASK MESSAGE 
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LR 

AH 

LA 

LA 

LR 

BCTR 

EX 

ALR 

LA 

LA 

LR 

BCTR 

EX 

ALR 

STH 

BAL 



LA 
B 



R8.R6 COPY BUFFER ADDRESS 

R8,HDRTDISP-BUFHDR(R6) POINT TO TEXT AREA 
R9.INVTASK ADDRESS INVALID TASK MESSAGE 
RIO.L'INVTASK LENGTH OF INVALID TASK MESSAGE 
R11.R10 SAVE THIS LENGTH 

R10.0 DECREMENT FOR EXECUTE 

RIO.COPYMSG COPY MESSAGE TEXT INTO BUFFER 
R8.R11 POINT TO POSITION AFTER MESSAGE 

R9, TVBOPID ADDRESS TASKID (OPID) 
RIO, L' TVBOPID LENGTH OF TASKID (OPID) 
R14.R10 COPY TVBOPID LENGTH 

R10.0 DECREMENT FOR EXECUTE 

R10.COPYMSG COPY MESSAGE TEXT INTO BUFFER 
R11.R14 CALCULATE TOTAL MESSAGE LENGTH 

R11,HDRMLENG-BUFHDR(R6) STORE MESSAGE LENGTH IN HEADER 
R14.SENDMSG SEND MESSAGE . 

IF THE MESSAGE SEND FAILS, JUST 
LEAVE WITH BAD RETURN CODE - WE 
TRIED. 
R15.ERRC0DE ERROR RETURN CODE 
EXIT LEAVE THE MODULE 



ENVIROK EQU * 
******************************************************* 

* BUILD THE LOG HEADER * 

* LOGHEADER => 'domainid hh:mm:ss opid' * 

* * 

*********************************************************************** 



Blank out log buffer 

BAL R14.CLRBFR 

Get DATE and TIME 

LA R8.L0GD0MID 
DSIDATIM AREA=(R8) 



Clear the buffer 



ADDRESS LOG DATIM 
GET DATE AND TIME 



* Overwrite date portion of DATIM with Domain Id 
* 

MVC ( L ' MVTCURAN , R8) , MVTCURAN 
* 

* Get opid 
* 

LA R9, TVBOPID ADDRESS TASKID (OPID) 

MVC 0PID(L'0PID),0(R9) Copy opid into log 
****************************************************************** 

* 

* Get text to be logged from command buffer. 



****************************************************************** 



L R6.CWBBUF 

LH R11,HDRMLENG-BUFHDR(R6) 

AH R6,HDRTDISP-BUFHDR(R6) 
* 

* Get length of the command 
* 

L R7.CWBPDB 

LA R8,PDBTABLE-DSIPDB(R7) 

SLR R9.R9 

IC R9,PDBLENG-PDBENTRY(R8) 

LA R9,1(R9) 

* 

* Check for no text 



ADDRESS COMMAND BUFFER 
Rll has total text length 
R6 points to text 



ADDRESS PDB 
ADDRESS PDB ENTRIES 
CLEAR WORK REG 
LENGTH OF COMMAND 
Add blank after command 



SR 
BNP 



R11.R9 
LOGIT 



SUBTRACT LENGTH OF COMMAND 
JUST LOG HEADER IF NO TEXT 
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AR R6.R9 



Add length to text pointer 



* Log text 1 buffer at a time until all text is logged 



LA 


R10.MAXTXTLN 


CR 


R11.R10 


BNL 


COPYTEXT 


LR 


R10.R11 


COPYTEXT EQU 


* 


SR 


R11.R10 


LR 


R9.R6 


AR 


R6.R10 


LA 


R8.L0GTEXT 


BCTR 


R1O.0 


EX 


R10.C0PYMSG 


LOGIT EQU 


* 



GET MAX TEXT WE CAN LOG 

Is text left > max 

No - Then log max 

Yes - Then log whats left 

Dec the total length 
Address text to be copied 
Update text pointer 
Address text area 
Decrement for execute 
Copy text into buffer 



L R7.CWBSWB Address the SWB 

LA R8.L0GBFR Address log buffer 

DSIWLS SWB=(R7),SAMREC=(R8) ,SAMLEN=SQLEN,SAMTASK=SQTASK 

R15 will have RC from DSIWLS 
LTR R15.R15 Was logging successful? 

BNZ SLOGERR No - inform the issuer 

Yes - check for more text 
R11.R11 More text? 

EXIT No - then exit 

R14.CLRBFR Yes - clear buffer 

CHKLEN Branch back to CHkLEN 



LTR 

BNP 

BAL 

B 

EQU 



SLOGERR 

****** 

* Get the Error message 
****** 

LA R6.MSGBFR 



ADDRESS MESSAGE BUFFER 



LR R8.R6 COPY BUFFER ADDRESS 

AH R8,HDRTDISP-BUFHDR(R6) POINT TO TEXT AREA 

LA R9.BADRC ADDRESS BAD RETURN CODE MESSAGE 

LA RIO.L'BADRC LENGTH OF MESSAGE 

LR R11.R10 SAVE THIS LENGTH 

BCTR R10.0 DECREMENT FOR EXECUTE 

EX R10.COPYMSG COPY MESSAGE TEXT INTO BUFFER 
*** 

Make the RC printable 



DECCONV 



EQU 

CVD 

MVC 

ED 

ALR 

MVC 

A 

STH 

BAL 



LA 



R15.DBLEW0RD 

MASK, =X' 402020202120' 

MASK.DBLEWORD+5 

R8.R11 

0(2,R8),MASK+4 

R11,=F'2' 



Convert value to dec 

Get the mask 

Edit the converted value 

Point to end of bad re msg 

Move to converted re to output 

Calculate total length 

R11,HDRMLENG-BUFHDR(R6) Store length in header 

R14.SENDMSG Send the message 

If message fails, just 
exit with bad return code 

R15.ERRCODE 



B EXIT 
*********************************************************************** 

* Send a message * 

*********************************************************************** 

SENDMSG DS 0H 

ST R14.SAVERET 

LA R6.MSGBFR 

L R7.CWBSWB 

CLI CBHTYPE-DSICBH(R3),CBH0ST CHECK FOR OST 

BE USEPSS USE DSIPSS IF OST 
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USEPSS 



EXITSUB 



CLI CBHTYPE-DSICBH(R3),CBHNNT CHECK FOR NNT 

BE USEPSS USE DSIPSS IF NNT 

DSIMQS BFR=(R6) ,SWB=(R7) ,AUTHRCV=YES 

B EXITSUB 

EQU * 

DSIPSS BFR*(R6) ,SWB=(R7) ,TYPE=OUTPUT 

EQU * 

L R14.SAVERET 



BR R14 
*********************************************************** 

* MODULE EXIT * 

*********************************************************************** 



EXIT 



EQU 
L 
L 
LM 



R13,4(R13) 

R14,12(R13) 

R0,R12,20(R13) 



BR R14 
*********************************************************************** 

* Routine to blank out buffer * 
*********************************************************************** 

* 

CLRBFR 

Save return address 

POINT TO LOG BUFFER 

AND THE NEXT POSITION 

PUT BLANK IN FIRST BYTE 

GET LENGTH OF LOG BUFFER 

DECREMENT FOR EXECUTE 

PROPAGATE BLANKS FOR ENTIRE BFR 

RESTORE RETURN ADDRESS 

RETURN 
*********************************************************************** 

*********************************************************************** 

* CONSTANTS, EQUATES, AUTODATA SET-UP, ETC. * 
*********************************************************************** 

DS OH 

COPYMSG MVC 0(0,R8),0(R9) 
********************************************************************** 

* ENSURE THAT NO TEXT LINE EXTENDS BEYOND THE TEXT AREA ALLOCATED * 

* FOR THE MESSAGE BUFFER IN AUTODATA. * 
********************************************************************** 



EQU 


* 


ST 


R14.SAVERET 


LA 


R9.L0GBFR 


LA 


R8,1(R9) 


MVI 


O^KX^' 


LA 


RIO.LOGBFRLN 


BCTR 


R10.0 


EX 


RIO, COPYMSG 


L 


R14.SAVERET 


BR 


R14 



SQTASK 


DC 


CL8'SQL0GTSK' 


SQLEN 


DC 


F'lOO' 


INVTASK 


DC 


CL32' COMMAND INVALID FOR THIS TASK - ' 


BADRC 


DC 


CL57'SL0G000 ERROR ENCOUNTERED ISSUING DSIWLS, RETURN CX 
ODE = ' 


ERRCODE 


EQU. 


4 


RO 


EQU 





Rl 


EQU 


1 


R2 


EQU 


2 


R3 


EQU 


3 


R4 


EQU 


4 


R5 


EQU 


5 


R6 


EQU 


6 


R7 


EQU 


7 


R8 


EQU 


8 


R9 


EQU 


9 


RIO 


EQU 


10 


Rll 


EQU 


11 


R12 


EQU 


12 


R13 


EQU 


13 


R14 


EQU 


14 


R15 


EQU 


15 


DSICWB 


DSECT 






ORG 


CWBADATD 


AUTOST 


EQU 


* START OF AUTODATA 
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SAVERET DS 
DBLEWORD DS 
MASK DS 
MSGBFR DS 

ORG 
MSGHDR DS 
LOGBFR EQU 

DS 
LOGDOMID DS 

DS 
OPID DS 

DS 
LOGHDRLN EQU 
LOGTEXT EQU 
TXTAREA DS 
MAXTXTLN EQU 
LOGBFRLN EQU 
AUTOEND EQU 



AUTOREM EQU 
END 



SAVE SPACE FOR RETURN ADDRESS 



***NOTE: This buffer header 
is not needed for sequential 
logging it is included for 
sending messages 



F 

D 

CL6 

CL(BUFHDRND-BUFHDR+1O0) 

MSGBFR 

CL(BUFHDRND-BUFHDR) 
* 

CL1 
CL8 
CL1 
CL8 
CL1 
*-LOGBFR 



CL81 

*-LOGTEXT 

*-LOGBFR 

* END OF AUTODATA 

THE FOLLOWING IS TO HELP WARN 
ABOUT INSUFFICIENT AUTODATA 

(L ' CWBADATD- (AUTOEND-AUTOST) ) 

ASEQLOG 
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Glossary 



This glossary defines important NCP, NetView, 
NetView/PC, SSP, and VTAM abbreviations and terms. 
It includes information from the IBM Dictionary of Com- 
puting, SC20-1699. Definitions from the American 
National Dictionary for Information Processing are 
identified by an asterisk (*). Definitions from draft pro- 
posals and working papers under development by the 
International Standards Organization, Technical Com- 
mittee 97, Subcommittee 1 are identified by the symbol 
(TC97). Definitions from the CC/77 Sixth Plenary 
Assembly Orange Book, Terms and Definitions and 
working documents published by the Consultative Com- 
mittee on International Telegraph and Telephone of the 
International Telecommunication Union, Geneva, 1980 
are preceded by the symbol (CCITT/ITU). Definitions 
from published sections of the ISO Vocabulary of Data 
Processing, developed by the International Standards 
Organization, Technical Committee 97, Subcommittee 1 
and from published sections of the ISO Vocabulary of 
Office Machines, developed by subcommittees of ISO 
Technical Committee 95, are preceded by the symbol 
(ISO). 

For abbreviations, the definition usually consists only of 
the words represented by the letters; for complete defi- 
nitions, see the entries for the words. 

Reference Words Used in the Entries 

The following reference words are used in this 
glossary: 

Deprecated term for. Indicates that the term should 
not be used. It refers to a preferred term, which is 
defined. 

Synonymous with. Appears in the commentary of a 
preferred term and identifies less desirable or less 
specific terms that have the same meaning. 

Synonym for. Appears in the commentary of a less 
desirable or less specific term and identifies the 
preferred term that has the same meaning. 

Contrast with. Refers to a term that has an opposed 
or substantively different meaning. 

See. Refers to multiple-word terms that have the 
same last word. 

See also. Refers to related terms that have similar 
(but not synonymous) meanings. 



abend. Abnormal end of task. 

abnormal end of task (abend). Termination of a task 
before its completion because of an error condition that 
cannot be resolved by recovery facilities while the task 
is executing. 



ACB. (1) In VTAM, access method control block. 
(2) In NCP, adapter control block. 

ACB name. (1) The name of an ACB macroinstruction. 
(2) A name specified in the ACBNAME parameter of a 
VTAM APPL statement. Contrast with network name. 

accept. For a VTAM application program, to establish 
a session with a logical unit (LU) in response to a CINIT 
request from a system services control point (SSCP). 
The session-initiation request may begin when a ter- 
minal user logs on, a VTAM application program issues 
a macroinstruction, or a VTAM operator issues a 
command. See also acquire (1). 

access method. A technique for moving data between 
main storage and input/output devices. 

access method control block (ACB). A control block 
that links an application program to VSAM or VTAM. 

accounting exit routine. In VTAM, an optional installa- 
tion exit routine that collects statistics about session 
initiation and termination. 

ACF/NCP. Advanced Communications Function for the 
Network Control Program. Synonym for NCP. 

ACF/SSP. Advanced Communications Function for the 
System Support Programs. Synonym for SSP. 

ACF/VTAM. Advanced Communications Function for 
the Virtual Telecommunications Access Method. 
Synonym for VTAM. 

acquire. (1) For a VTAM application program, to ini- 
tiate and establish a session with another logical unit 
(LU). The acquire process begins when the application 
program issues a macroinstruction. See also accept. 
(2) To take over resources that were formerly con- 
trolled by an access method in another domain, or to 
resume control of resources that were controlled by 
this domain but released. Contrast with release. See 
also resource takeover. 

active. (1) The state a resource is in when it has been 
activated and is operational. Contrast with inactive, 
pending, and inoperative.. (2) Pertaining to a major or 
minor node that has been activated by VTAM. Most 
resources are activated as part of VTAM start proc- 
essing or as the result of a VARY ACT command. 

adapter control block (ACB). In NCP, a control block 
that contains line control information and the states of 
I/O operations for BSC lines, SS lines, or SDLC links. 



adaptive session pacing. 

session-level pacing. 



Synonym for adaptive 
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adaptive session-level pacing. A form of session-level 
pacing in which session components exchange pacing 
windows that may vary in size during the course of a 
session. This allows transmission to adapt dynamically 
to variations in availability and demand of buffers on a 
session by session basis. Session pacing occurs 
within independent stages along the session path 
according to local congestion at the intermediate 
nodes. Synonymous with adaptive session pacing. 
See pacing, session-level pacing, and virtual route 
pacing. 

alert. (1) In SNA, a record sent to a system problem 
management focal point to communicate the existence 
of an alert condition. (2) In the NetView program, a 
high priority event that warrants immediate attention. 
This data base record is generated for certain event 
types that are defined by user-constructed filters. 

alias name. A name defined in a host used to repre- 
sent a logical unit name, logon mode table name, or 
class-of-service name in another network. This name 
is defined to a name translation program when the 
alias name does not match the real name. The alias 
name translation program is used to associate the real 
and alias names. 

allocate. A logical unit (LU) 6.2 application program 
interface (API) verb used to assign a session to a con- 
versation for the conversation's use. Contrast with 
deallocate. 

API. Application program interface. 



automatic logon. (1) A process by which VTAM auto- 
matically creates a session-initiation request to estab- 
lish a session between two logical units (LUs). The 
session will be between a designated primary logical 
unit (PLU) and a secondary logical unit (SLU) that is 
neither queued for nor in session with another PLU. 
See also controlling application program and control- 
ling logical unit. (2) In VM, a process by which a 
virtual machine is initiated by other than the user of 
that virtual machine. For example, the primary VM 
operator's virtual machine is activated automatically 
during VM initialization. 

available. In VTAM, pertaining to a logical unit that is 
active, connected, enabled, and not at its session limit. 

basic conversation. A conversation that supports the 
functions of the basic conversation protocol boundary 
defined by LU 6.2. That format requires data to be sent 
as logical records consisting of a 2-byte length prefix 
followed by the data. See also mapped conversation. 

begin bracket. In SNA, the value (binary 1) of the 
begin-bracket indicator in the request header (RH) of 
the first request in the first chain of a bracket; the value 
denotes the start of a bracket. Contrast with end 
bracket. See also bracket. 

bidder. In SNA, the LU-LU half-session defined at 
session activation as having to request and receive 
permission from the other LU-LU half-session to begin 
a bracket. Contrast with first speaker. See also 
bracket protocol and contention. 



application program. (1) A program written for or by a 
user that applies to the user's work. (2) A program 
used to connect and communicate with stations in a 
network, enabling users to perform application-oriented 
activities. 



BIU segment. In SNA, the portion of a basic informa- 
tion unit (BIU) that is contained within a path informa- 
tion unit (PIU). It consists of either a request/response 
header (RH) followed by all or a portion of a 
request/response unit (RU), or only a portion of an RU. 



application program interface (API). (1) The formally 
defined programming language interface between an 
IBM system control program or licensed program and 
its user. (2) The interface through which an application 
program interacts with an access method. In VTAM, it 
is the language structure used in control blocks so that 
application programs can reference them and be identi- 
fied to VTAM. 

attaching device. Any device that is physically con- 
nected to a network and can communicate over the 
network. 

authorization exit routine. In VTAM, an optional instal- 
lation exit routine that approves or disapproves 
requests for session initiation. 

authorized receiver. In the NetView program, an 
authorized operator who receives all the unsolicited 
and authorized-receiver messages not assigned to a 
specific operator. 



blocking of PIUs. In SNA, an optional function of path 
control that combines multiple path information units 
(PIUs) into a single basic transmission unit (BTU). 

boundary function. (1) A capability of a subarea node 
to provide protocol support for attached peripheral 
nodes, such as: (a) interconnecting subarea path 
control and peripheral path control elements, (b) per- 
forming session sequence numbering for low-function 
peripheral nodes, and (c) providing session-level 
pacing support. (2) The component that provides these 
capabilities. See also boundary node, network 
addressable unit (NAU), peripheral path control, 
subarea node, and subarea path control. 

boundary node. (1) A subarea node with boundary 
function. See subarea node (including illustration). 
See also boundary function. (2) The programming 
component that performs FID2 (format identification 
type 2) conversion, channel data link control, pacing, 
and channel or device error recovery procedures for a 
locally attached station. These functions are similar to 
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those performed by a network control program for an 
NCP-attached station. 



cation lines. Contrast with link-attached. Synonymous 
with local. 



bracket. In SNA, one or more chains of request units 
(RUs) and their responses that are exchanged between 
the two LU-LU half-sessions and that represent a trans- 
action between them. A bracket must be completed 
before another bracket can be started. Examples of 
brackets are data base inquiries/replies, update trans- 
actions, and remote job entry output sequences to work 
stations. See also begin bracket and end bracket. 

bracket protocol. In SNA, a data flow control protocol 
in which exchanges between the two LU-LU 
half-sessions are achieved through the use of brackets, 
with one LU designated at session activation as the first 
speaker and the other as the bidder. The bracket pro- 
tocol involves bracket initiation and termination rules. 
See also bidder and first speaker. 

browse. A way of looking at a file that does not allow 
you to change it. 

buffer. A portion of storage for temporarily holding 
input or output data. 

call. (1) * (ISO) The action of bringing a computer 
program, a routine, or a subroutine into effect, usually 
by specifying the entry conditions and jumping to an 
entry point. (2) To transfer control to a procedure, 
program, routine, or subroutine. (3) The actions nec- 
essary to make a connection between two stations. 
(4) To attempt to contact a user, regardless of whether 
the attempt is successful. 

CALLOUT. The logical channel type on which the data 
terminal equipment (DTE) can send a call, but cannot 
receive one. 

calling. * (ISO) The process of transmitting selection 
signals in order to establish a connection between data 
stations. 

CCP. Configuration control program facility. 

CDRM. Cross-domain resource manager. 

CDRSC. Cross-domain resource. 



chain. (1) A group of logically linked records. (2) 
RU chain. 



See 



channel. * A path along which signals can be sent, for 
example, data channel, output channel. See data 
channel and input/output channel. See also link. 

channel-attached. (1) Pertaining to the attachment of 
devices directly by input/output channels to a host 
processor. (2) Pertaining to devices attached to a con- 
trolling unit by cables, rather than by telecommuni- 



character-coded. Synonym for unformatted. 

class of service (COS). In SNA, a designation of the 
path control network characteristics, such as path 
security, transmission priority, and bandwidth, that 
apply to a particular session. The end user designates 
class of service at session initiation by using a sym- 
bolic name that is mapped into a list of virtual routes, 
any one of which can be selected for the session to 
provide the requested level of service. 

cleanup. A network services request, sent by a system 
services control unit (SSCP) to a logical unit (LU), that 
causes a particular LU-LU session with that LU to be 
ended immediately and without the participation of 
either the other LU or its SSCP. 

CLIST. Command list. 

CMS. Conversational Monitor System. 

CNM. Communication network management. 

command. (1) A request from a terminal for the per- 
formance of an operation or the execution of a partic- 
ular program. (2) In SNA, any field set in the 
transmission header (TH), request header (RH), and 
sometimes portions of a request unit (RU), that initiates 
an action or that begins a protocol; for example: (a) 
Bind Session (session-control request unit), a 
command that activates an LU-LU session, (b) the 
change-direction indicator in the RH of the last RU of a 
chain, (c) the virtual route reset window indicator in a 
FID4 transmission header. See also VTAM operator 
command. 

command facility. The component of the NetView 
program that is a base for command processors that 
can monitor, control, automate, and improve the opera- 
tion of a network. 

command list. A list of commands and statements 
designed to perform a specific function for the user. 
Command lists can be written in REXX or in NetView 
command list language. 

command procedure. Either a command processor 
written in a high-level language (HLL) or a command 
list. See also command list and command processor. 

command processor. (1) A program that performs an 
operation specified by a command. (2) In the NetView 
program, a user-written module designed to perform a 
specific function. Command processors, which can be 
written in assembler or a high-level language (HLL), 
are invoked as commands. 

communication line. Deprecated term for telecommu- 
nication line and transmission line. 



Glossary 249 



communication management configuration host node. 

The type 5 host processor in a communication manage- 
ment configuration that does all network-control func- 
tions in the network except for the control of devices 
channel-attached to data hosts. Synonymous with com- 
munication management host. Contrast with data host 
node. 

communication management host. Synonym for com- 
munication management configuration host node. Con- 
trast with data host. 

communication network management (CNM). The 

process of designing, installing, operating, and man- 
aging the distribution of information and controls 
among end users of communication systems. 

communication network management (CNM) applica- 
tion program. A VTAM application program that issues 
and receives formatted management services request 
units for physical units. For example, the NetView 
program. 

communication network management (CNM) interface. 

The interface that the access method provides to an 
application program for handling data and commands 
associated with communication system management. 
CNM data and commands are handled across this inter- 
face. 

communication network management (CNM) 
processor. A program that manages one of the func- 
tions of a communications system. A CNM processor is 
executed under control of the NetView program. 



connection. Synonym for physical connection. 

contention. A situation in which two logical units (LUs) 
that are connected by an LU 6.2 session both attempt to 
allocate the session for a conversation at the same 
time. The control operator assigns "winner" and 
"loser" status to the LUs so that processing may con- 
tinue on an orderly basis. The contention loser 
requests permission from the contention winner to allo- 
cate a conversation on the session, and the contention 
winner either grants or rejects the request. See also 
bidder. 

control block. (1) (ISO) A storage area used by a 
computer program to hold control information. (2) In 
the IBM Token-Ring Network, a specifically formatted 
block of information provided from the application 
program to the Adapter Support Interface to request an 
operation. 

control point (CP). (1) A system services control point 
(SSCP) that provides hierarchical control of a group of 
nodes in a network. (2) A control point (CP) local to a 
specific node that provides control of that node, either 
in the absence of SSCP control (for type 2.1 nodes 
engaged in peer to peer communication) or to supple- 
ment SSCP control. 

control program (CP). The VM operating system that 
manages the real processor's resources and is respon- 
sible for simulating System/370s for individual users. 

controller. A unit that controls input/output operations 
for one or more devices. 



component. A command that (a) controls the termi- 
nal's screen (using the DSIPSS macro 
(TYPE = ASYPANEL) or the VIEW command), (b) allows 
the operator to enter NetView commands, and (c) can 
resume when such commands are complete. 

composite end node (CEN). A group of nodes made up 
of a single type 5 node and its subordinate type 4 nodes 
that together support type 2.1 protocols. To a type 2.1 
node, a CEN appears as one end node. For example, 
NCP and VTAM act as a composite end node. 

configuration control program (CCP) facility. An SSP 

interactive application program facility by which config- 
uration definitions for the IBM 3710 Network Controller 
can be created, modified, and maintained. 

configuration services. In SNA, one of the types of 
network services in the control point (CP) and in the 
physical unit (PU); configuration services activate, 
deactivate, and maintain the status of physical units, 
links, and link stations. Configuration services also 
shut down and restart network elements and modify 
path control routing tables and address-translation 
tables. See also maintenance services, management 
services, network services, and session services. 



controlling application program. In VTAM, an applica- 
tion program with which a secondary logical unit (other 
than an application program) is automatically put in 
session whenever the secondary logical unit is avail- 
able. See also automatic logon and controlling logical 
unit. 

controlling logical unit. In VTAM, a logical unit with 
which a secondary logical unit (other than an applica- 
tion program) is automatically put in session whenever 
the secondary logical unit is available. A controlling 
logical unit can be either an application program or a 
device-type logical unit. See also automatic logon and 
controlling application program. 

conversation. In SNA, a logical connection between 
two transaction programs using an LU 6.2 session. 
Conversations are delimited by brackets to gain exclu- 
sive use of a session. 

Conversational Monitor System (CMS). A VM applica- 
tion program for general interactive time sharing, 
problem solving, and program development. 

converted command. An intermediate form of a 
character-coded command produced by VTAM through 
use of an unformatted system services definition table. 
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The format of a converted command is fixed; the unfor- 
matted system services definition table must be con- 
structed in such a manner that the character-coded 
command (as entered by a logical unit) is converted 
into the predefined, converted command format. See 
also unformatted. 

COS. Class of service. 

CP. (1) Control program. (2) Control point. 

cross-domain. In SNA, pertaining to control of 
resources involving more than one domain. 

cross-domain resource (CDRSC). A resource owned 
by a cross-domain resource manager (CDRM) in 
another domain but known by the CDRM in this domain 
by network name and associated CDRM. 



data services request block (DSRB). The control block 
in the NetView program that contains information that a 
data services command processor (DSCP) needs to 
communicate with the data services task (DST). 

data services task (DST). The NetView subtask that 
gathers, records, and manages data in a VSAM file 
and/or a network device that contains network manage- 
ment information. 

data set. The major unit of data storage and retrieval, 
consisting of a collection of data in one of several pre- 
scribed arrangements and described by control infor- 
mation to which the system has access. 

DBCS. Double-byte character set. 

ddname. Data definition name. 



cross-domain resource manager (CDRM). In VTAM, 
the function in the system services control point (SSCP) 
that controls initiation and termination of cross-domain 
sessions. 



deallocate. A logical unit (LU) 6.2 application program 
interface (API) verb that terminates a conversation, 
thereby freeing the session for a future conversation. 
Contrast with allocate. 



data channel. 

channel. 



Synonym for input/output channel. See 



data flow control (DFC) layer. In SNA, the layer within 
a half-session that (1) controls whether the half-session 
can send, receive, or concurrently send and receive 
request units (RUs); (2) groups related RUs into RU 
chains; (3) delimits transactions via the bracket pro- 
tocol; (4) controls the interlocking of requests and 
responses in accordance with control modes specified 
at session activation; (5) generates sequence numbers; 
and (6) correlates requests and responses. 



definite response (DR). In SNA, a value in the 
form-of-response-requested field of the request header. 
The value directs the receiver of the request to return a 
response unconditionally, whether positive or negative, 
to that request. Contrast with exception response and 
no response. 

definition statement. (1) In VTAM, the statement that 
describes an element of the network. (2) In NCP, a 
type of instruction that defines a resource to the NCP. 
See Figure 18, Figure 19, and Figure 20 on page 252. 
See also macroinstruction. 



data host. Synonym for data host node. Contrast with 
communication management configuration host. 

data host node. In a communication management con- 
figuration, a type 5 host node that is dedicated to proc- 
essing applications and does not control network 
resources, except for its channel-attached or communi- 
cation adapter-attached devices. Synonymous with 
data host. Contrast with communication management 
configuration host node. 

data link. In SNA, synonym for link. 
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Figure 18. Example of a Language Statement 



data link control (DLC) layer. In SNA, the layer that 
consists of the link stations that schedule data transfer 
over a transmission medium connecting two nodes and 
perform error control for the link connection. Examples 
of data link control are SDLC for serial-by-bit link con- 
nection and data link control for the System/370 
channel. 

data services command processor (DSCP). A compo- 
nent that structures a request for recording and 
retrieving data in the application program's data base 
and for soliciting data from a device in the network. 
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Figure 19. NCP Examples 
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Figure 20. VTAM Examples 

device. An input/output unit such as a terminal, 
display, or printer. See attaching device. 

direct call. (ISO) A facility that permits calling without 
requiring the user to provide address selection signals; 
the network interprets the call request signal as an 
instruction to establish a connection to one or more 
predetermined data stations. 

directory. In VM, a control program (CP) disk that 
defines each virtual machine's normal configuration. 

disabled. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is temporarily not ready to establish 
LU-LU sessions. An initiate request for a session with 
a disabled logical unit (LU) can specify that the session 
be queued by the SSCP until the LU becomes enabled. 
The LU can separately indicate whether this applies to 
its ability to act as a primary logical unit (PLU) or a sec- 
ondary logical unit (SLU). See also enabled and inhib- 
ited. 

display. (1) To present information for viewing, 
usually on a terminal screen or a hard-copy device. 
(2) A device or medium on which information is pre- 
sented, such as a terminal screen. (3) Deprecated 
term for panel. 

domain. (1) An access method, its application pro- 
grams, communication controllers, connecting lines, 
modems, and attached terminals. (2) In SNA, a system 
services control point (SSCP) and the physical units 
(PUs), logical units (LUs), links, link stations, and all the 
associated resources that the SSCP has the ability to 
control by means of activation requests and deacti- 
vation requests. See system services control point 
domain and type 2.1 node control point domain.. See 
also single-domain network and multiple-domain 
network. 

domain operator. In a multiple-domain network, the 
person or program that controls the operation of the 
resources controlled by one system services control 
point. Contrast with network operator (2). 



double-byte character set (DBCS). A character set, 
such as Japanese, in which each character is repres- 
ented by a two-byte code. 

downstream. In the direction of data flow from the host 
to the end user. Contrast with upstream. 

drop. In the IBM Token-Ring Network, a cable that 
leads from a faceplate to the to the distribution panel in 
a wiring closet. When the IBM Cabling System is used 
with the IBM Token-Ring Network, a drop may form part 
of a lobe. 

DSCP. Data services command processor. 

DST. Data services task. 

EBCDIC. * Extended binary-coded decimal inter- 
change code. A coded character set consisting of 8-bit 
coded characters. 

ECB. Event control block. 

echo. The return of characters to the originating SS 
device to verify that a message was sent correctly. 

ED. Enciphered data. 

element. (1) A field in the network address. (2) The 
particular resource within a subarea identified by the 
element address. See also subarea. 

Emulation Program (EP). An IBM control program that 
allows a channel-attached 3705 or 3725 communication 
controller to emulate the functions of an IBM 2701 Data 
Adapter Unit, an IBM 2702 Transmission Control, or an 
IBM 2703 Transmission Control. See also network 
control program. 

enabled. In VTAM, pertaining to a logical unit (LU) that 
has indicated to its system services control point 
(SSCP) that it is now ready to establish LU-LU sessions. 
The LU can separately indicate whether this prevents it 
from acting as a primary logical unit (PLU) or as a sec- 
ondary logical unit (SLU). See also disabled and inhib- 
ited. 

enciphered data (ED). Data whose meaning is con- 
cealed from unauthorized users. 

end bracket. In SNA, the value (binary 1) of the end 
bracket indicator in the request header (RH) of the first 
request of the last chain of a bracket; the value denotes 
the end of the bracket. Contrast with begin bracket. 
See also bracket. 

end node. A type 2.1 node that does not provide any 
intermediate routing or session services to any other 
node. For example, APPC/PC is an end node. See 
composite end node, node, and fype 2.1 node. 
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entry point. An SNA node that provides distributed 
network management support. It may be a type 2, type 
2.1, type 4, or type 5 node. It sends SNA-formatted 
network management data about itself and the 
resources it controls to a focal point for centralized 
processing, and it receives and executes focal point ini- 
tiated commands to manage and control its resources. 

EP. Emulation Program. 

ER. (1) Explicit route. (2) Exception response. 

•vent. (1) In the NetView program, a record indicating 
irregularities of operation in physical elements of a 
network. (2) An occurrence of significance to a task; 
typically, the completion of an asynchronous operation, 
such as an input/output operation. 

event control block (ECB). A control block used to rep- 
resent the status of an event. 

exception response (ER). In SNA, a value in the 
form-of-response-requested field of a request header 
(RH). An exception response is sent only if a request is 
unacceptable as received or cannot be processed. 
Contrast with definite response and no response. See 
also negative response. 

EXEC. In a VM operating system, a user-written 
command file that contains CMS commands, other 
user-written commands, and execution control state- 
ments, such as branches. 

exit list (EXLST). In VSAM and VTAM, a control block 
that contains the addresses of routines that receive 
control when specified events occur during execution; 
for example, routines that handle 
session-establishment request processing or I/O 
errors. 



route number, and a reverse explicit route number. 
Contrast with virtual route (VR). See also path and 
route extension. 

feature. A particular part of an IBM product that a cus- 
tomer can order separately. 

field-formatted. Pertaining to a request or response 
that is encoded into fields, each having a specified 
format such as binary codes, bit-significant flags, and 
symbolic names. Contrast with character-coded. 

first speaker. In SNA, the LU-LU half-session defined 
at session activation as: (1) able to begin a bracket 
without requesting permission from the other LU-LU 
half-session to do so, and (2) winning contention if both 
half-sessions attempt to begin a bracket simultane- 
ously. Contrast with bidder. See also bracket protocol. 

flow control. In SNA, the process of managing the rate 
at which data traffic passes between components of the 
network. The purpose of flow control is to optimize the 
rate of flow of message units, with minimum congestion 
in the network; that is, to neither overflow the buffers at 
the receiver or at intermediate routing nodes, nor leave 
the receiver waiting for more message units. See also 
adaptive session-level pacing, pacing, session-level 
pacing, and virtual route pacing. 

focal point. An entry point that provides centralized 
management and control for other entry points for one 
or more network management categories. 

formatted system services. A portion of VTAM that 
provides certain system services as a result of 
receiving a field-formatted command, such as an Ini- 
tiate or Terminate command. Contrast with unfor- 
matted system services (USS). See also 
field-formatted. 



exit routine. Any of several types of special-purpose 
user-written routines. See accounting exit routine, 
authorization exit routine, logon-interpret routine, 
virtual route selection exit routine, EXLST exit routine, 
and RPL exit routine. 

EXLST exit routine. In VTAM, a routine whose address 
has been placed in an exit list (EXLST) control block. 
The addresses are placed there with the EXLST macro- 
instruction, and the routines are named according to 
their corresponding operand; hence DFASY exit 
routine, TPEND exit routine, RELREQ exit routine, and 
so forth. All exit list routines are coded by the VTAM 
application programmer. Contrast with RPL exit 
routine. 

explicit route (ER). In SNA, the path control network 
elements, including a specific set of one or more trans- 
mission groups, that connect two subarea nodes. An 
explicit route is identified by an origin subarea 
address, a destination subarea address, an explicit 



frame. (1) The unit of transmission in some local area 
networks, including the IBM Token-Ring Network. It 
includes delimiters, control characters, information, 
and checking characters. (2) In SDLC, the vehicle for 
every command, every response, and all information 
that is transmitted using SDLC procedures. 

full-screen mode. A form of panel presentation in the 
NetView program where the contents of an entire ter- 
minal screen can be displayed at once. Full-screen 
mode can be used for fill-in-the-blanks prompting. Con- 
trast with line mode. 

generation. The process of assembling and link 
editing definition statements so that resources can be 
identified to all the necessary programs in a network. 

generic alert. Encoded alert information that uses 
code points (defined by IBM and possibly customized 
by users or application programs) stored at an alert 
receiver, such as the NetView program. 
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group. In the NetView/PC program, to identify a set of 
application programs that are to run concurrently. 

half-session. In SNA, a component that provides func- 
tion management data (FMD) services, data flow 
control, and transmission control for one of the ses- 
sions of a network addressable unit (NAU). See also 
primary half-session and secondary half-session. 

hard copy. A printed copy of machine output in a visu- 
ally readable form; for example, printed reports, 
listings, documents, summaries, or network logs. 

hard-copy task (HCT). The NetView subtask that con- 
trols the passage of data between the NetView program 
and the hard-copy device. 

hardware monitor. The component of the NetView 
program that helps identify network problems, such as 
hardware, software, and microcode, from a central 
control point using interactive display techniques. 

HCT. Hard-copy task. 

help panel. An online display that tells you how to use 
a command or another aspect of a product. See task 
panel. 

high-level language (HLL). A programming language 
that does not reflect the structure of any particular com- 
puter or operating system. For NetView Release 3, the 
high-level languages are PL/I and C. 



initiate. A network services request sent from a logical 
unit (LU) to a system services control point (SSCP) 
requesting that an LU-LU session be established. 

inoperative. The condition of a resource that has been 
active, but is not. The resource may have failed, 
received an INOP request, or is suspended while a 
reactivate command is being processed. See also 
inactive. 

input/output channel. (1) (ISO) In a data processing 
system, a functional unit that handles the transfer of 
data between internal and peripheral equipment. (2) In 
a computing system, a functional unit, controlled by a 
processor, that handles the transfer of data between 
processor storage and local peripheral devices. Syn- 
onymous with data channel. See channel. See also 
link. 

Interactive System Productivity Facility (ISPF). An IBM 

licensed program that serves as a full-screen editor 
and dialogue manager. Used for writing application 
programs, it provides a means of generating standard 
screen panels and interactive dialogues between the 
application programmer and terminal user. 

interface. * A shared boundary. An interface might be 
a hardware component to link two devices or it might 
be a portion of storage or registers accessed by two or 
more computer programs. 

ISPF. Interactive System Productivity Facility. 



host node. A node providing an application program 
interface (API) and a common application interface. 
See boundary node, node, peripheral node, subarea 
host node, and subarea node. See also boundary func- 
tion and node type. 

immediate command. In the NetView program, a 
command (such as GO, CANCEL, or RESET) that can be 
executed while a regular command is being processed. 

inactive. Describes the state of a resource that has not 
been activated or for which the VARY INACT command 
has been issued. Contrast with active. See also inop- 
erative. 



item. In CCP, any of the components, such as commu- 
nication controllers, lines, cluster controllers, and ter- 
minals, that comprise an IBM 3710 Network Controller 
configuration. 

JCL. Job control language. 

job control language (JCL). * A problem-oriented lan- 
guage designed to express statements in a job that are 
used to identify the job or describe its requirements to 
an operating system. 

Kanji. An ideographic character set used in Japanese. 
See also double-byte character set. 



information (I) format. 

transfer. 



A format used for information 



inhibited. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is not ready to establish LU-LU sessions. 
An initiate request for a session with an inhibited LU 
will be rejected by the SSCP. The LU can separately 
indicate whether this applies to its ability to act as a 
primary logical unit (PLU) or as a secondary logical 
unit (SLU). See also enabled and disabled. 



keyword. (1) (TC97) A lexical unit that, in certain con- 
texts, characterizes some language construction. (2) * 
One of the predefined words of an artificial language. 
(3) One of the significant and informative words in a 
title or document that describes the content of that doc- 
ument. (4) A name or symbol that identifies a param- 
eter. (5) A part of a command operand that consists of 
a specific character string (such as DSNAME = ). See 
also definition statement and keyword operand. Con- 
trast with positional operand. 

keyword operand. An operand that consists of a 
keyword followed by one or more values (such as 
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DSNAME = HELLO). See also definition statement. 
Contrast with positional operand. 

keyword parameter. A parameter that consists of a 
keyword followed by one or more values. 

line. See communication line. 

line mode. A form of screen presentation in which the 
information is presented a line at a time in the message 
area of the terminal screen. Contrast with full-screen 
mode. 

link. In SNA, the combination of the link connection 
and the link stations joining network nodes; for 
example: (1) a System/370 channel and its associated 
protocols, (2) a serial-by-bit connection under the 
control of Synchronous Data Link Control (SDLC). A 
link connection is the physical medium of transmission. 
A link, however, is both logical and physical. Synony- 
mous with data link. See Figure 21 on page 256. 



logical unit (LU) services. In SNA, capabilities in a 
logical unit to: (1) receive requests from an end user 
and, in turn, issue requests to the system services 
control point (SSCP) in order to perform the requested 
functions, typically for session initiation; (2) receive 
requests from the SSCP, for example to activate LU-LU 
sessions via Bind Session requests; and (3) provide 
session presentation and other services for LU-LU ses- 
sions. See also physical unit (PU) services. 

logical unit (LU) 6.2. A type of logical unit that sup- 
ports general communication between programs in a 
distributed processing environment. LU 6.2 is charac- 
terized by (1) a peer relationship between session part- 
ners, (2) efficient utilization of a session for multiple 
transactions, (3) comprehensive end-to-end error proc- 
essing, and (4) a generic application program interface 
(API) consisting of structured verbs that are mapped 
into a product implementation. 

logmode table. Synonym for logon mode table. 



link-attached. Pertaining to devices that are physically 
connected by a telecommunication line. Contrast with 
channel-attached. Synonymous with remote. 

link connection segment. A portion of the configuration 
that is located between two resources listed consec- 
utively in the service point command service (SPCS) 
query link configuration request list. 

load module. (ISO) A program unit that is suitable for 
loading into main storage for execution; it is usually the 
output of a linkage editor. 

local. Pertaining to a device that is attached to a con- 
trolling unit by cables, rather than by a telecommuni- 
cation line. Synonymous with channel-attached. 

local address. In SNA, an address used in a peripheral 
node in place of an SNA network address and trans- 
formed to or from an SNA network address by the 
boundary function in a subarea node. 

logical record. (1) (TC97) A set of related data or 
words considered to be a record from a logical view- 
point. (2) A unit of information normally pertaining to a 
single subject; a logical record is that user record 
requested of or given to the data management function. 
See also basic conversation. 

logical unit (LU). In SNA, a port through which an end 
user accesses the SNA network and the functions pro- 
vided by system services control points (SSCPs). An 
LU can support at least two sessions— one with an 
SSCP and one with another LU— and may be capable of 
supporting many sessions with other LUs. See also 
network addressable unit (NAU), peripheral LU, phys- 
ical unit (PU), system services control point (SSCP), 
primary logical unit (PLU), and secondary logical unit 
(SLU). 



logoff. In VTAM, an unformatted session termination 
request. 

log on. To initiate a session. 

logon. In VTAM, an unformatted session initiation 
request for a session between two logical units. See 
automatic logon and simulated logon. See also 
session-initiation request. 

logon mode table. In VTAM, a set of entries for one or 
more logon modes. Each logon mode is identified by a 
logon mode name. Synonymous with logmode table. 

logon-interpret routine. In VTAM, an installation exit 
routine, associated with an interpret table entry, that 
translates logon information. It may also verify the 
logon. 

LU. Logical unit. 

LU type. In SNA, the classification of an LU-LU session 
in terms of the specific subset of SNA protocols and 
options supported by the logical units (LUs) for that 
session, namely: 

The mandatory and optional values allowed in the 
session activation request. 

The usage of data stream controls, function man- 
agement headers (FMHs), request unit (RU) param- 
eters, and sense codes. 

Presentation services protocols such as those 
associated with FMH usage. 

LU types 0, 1, 2, 3, 4, 6.1, 6.2, and 7 are defined. 

LU-LU session. In SNA, a session between two logical 
units (LUs) in an SNA network. It provides communi- 
cation between two end users, or between an end user 
and an LU services component. 
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Figure 21. Links and Path Controls 

LU-LU session type. A deprecated term for LU type. 

LU 6.2. Logical unit 6.2. 

macroinstruction. (1) An instruction that when exe- 
cuted causes the execution of a predefined sequence of 
instructions in the same source language. (2) In 
assembler programming, an assembler language state- 
ment that causes the assembler to process a prede- 
fined set of statements called a macro definition. The 



statements normally produced from the macro defi- 
nition replace the macroinstruction in the program. 
See also definition statement. 

maintenance services. In SNA, one of the types of 
network services in system services control points 
(SSCPs) and physical units (PUs). Maintenance ser- 
vices provide facilities for testing links and nodes and 
for collecting and recording error information. See 
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also configuration services, management services, 
network services, and session services. 

major node. In VTAM, a set of resources that can be 
activated and deactivated as a group. See node and 
minor node. 

management services. In SNA, one of the types of 
network services in control points (CPs) and physical 
units (PUs). Management services are the services 
provided to assist in the management of SNA networks, 
such as problem management, performance and 
accounting management, configuration management 
and change management. See also configuration ser- 
vices, maintenance services, network services, and 
session services. 

mapped conversation. A type of conversation in which 
the data to be sent or received can be in a user-defined 
format. A logical unit (LU) that supports mapped con- 
versations converts the user data to a format suitable 
for the basic conversation protocol boundary. See also 
conversation and basic conversation. 

Medium Access Control (MAC). The sublayer of DLC 
that supports medium-dependent functions and uses 
the services of the physical layer to provide services to 
Logical Link Control (LLC). The MAC sublayer includes 
the medium access port. 

medium access control (MAC) procedure. (TC97) In a 
local area network, the part of the protocol that governs 
access to the transmission medium independently of 
the physical characteristics of the medium, but takes 
into account the topological aspects of the network, in 
order to enable the exchange of data between data 
stations. 

message. (1) (TC97) A group of characters and 
control bit sequences transferred as an entity. (2) In 
VTAM, the amount of function management data (FMD) 
transferred to VTAM by the application program with 
one SEND request. 

migration. Installing a new version or release of a 
program when an earlier version or release is already 
in place. 

minor node. In VTAM, a uniquely-defined resource 
within a major node. See node and major node. 

module. * A program unit that is discrete and identifi- 
able with respect to compiling, combining with other 
units, and loading; for example, the input to or output 
from an assembler, compiler, linkage editor, or execu- 
tive routine. 

monitor. In the IBM Token-Ring Network, the function 
required to initiate the transmission of a token on the 
ring and to provide soft-error recovery in case of lost 
tokens, circulating frames, or other difficulties. The 
capability is present in all ring stations. 



multiple-domain network. In SNA, a network with more 
than one system services control point (SSCP). Con- 
trast with single-domain network. 

Multiple Virtual Storage (MVS). An IBM licensed 
program whose full name is the Operating 
System/Virtual Storage (OS/VS) with Multiple Virtual 
Storage/System Product for System/370. It is a soft- 
ware operating system controlling the execution of pro- 
grams. 

Multiple Virtual Storage for Extended Architecture 
(MVS/XA). An IBM licensed program whose full name 
is the Operating System/Virtual Storage (OS/VS) with 
Multiple Virtual Storage/System Product for Extended 
Architecture. Extended architecture allows 31-bit 
storage addressing. MVS/XA is a software operating 
system controlling the execution of programs. 

MVS. Multiple Virtual Storage operating system. 

MVS/XA. Multiple Virtual Storage for Extended Archi- 
tecture operating system. 

NAU. Network addressable unit. 

NC. Network control. 

NCCF. Network Communications Control Facility. 

NCP. (1) Network Control Program (IBM licensed 
program). Its full name is Advanced Communications 
Function for the Network Control Program. Synony- 
mous with ACF/NCP. (2) Network control program 
(general term). 

negative response (NR). In SNA, a response indicating 
that a request did not arrive successfully or was not 
processed successfully by the receiver. Contrast with 
positive response. See exception response. 

NetView. A system 370-based IBM licensed program 
used to monitor a network, manage it, and diagnose its 
problems. 

NetView command list language. An interpretive lan- 
guage unique to the NetView program that is used to 
write command lists. 

NetView-NetView task (NNT). The task under which a 
cross-domain NetView operator session runs. See 
operator station task. 

NetView/PC. A PC-based IBM licensed program 
through which application programs can be used to 
monitor, manage, and diagnose problems in IBM 
Token-Ring networks, non-SNA communication 
devices, and voice networks. 

network. (1) (TC97) An interconnected group of 
nodes. (2) In data processing, a user application 
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network. See path control network, public network, 
SNA network, subarea network, type 2.1 network, and 
user-application network. 

network address. In SNA, an address, consisting of 
subarea and element fields, that identifies a link, a link 
station, or a network addressable unit. Subarea nodes 
use network addresses; peripheral nodes use local 
addresses. The boundary function in the subarea node 
to which a peripheral node is attached transforms local 
addresses to network addresses and vice versa. See 
local address. See also network name. 

network addressable unit (NAU). In SNA, a logical unit, 
a physical unit, or a system services control point. It is 
the origin or the destination of information transmitted 
by the path control network. Each NAU has a network 
address that represents it to the path control network. 
See also network name, network address, and path 
control network. 

Network Communications Control Facility (NCCF). An 

IBM licensed program that is a base for command 
processors that can monitor, control, automate, and 
improve the operations of a network. Its function is 
included and enhanced in NetView's command facility. 

network control (NC). In SNA, an RU category used for 
requests and responses exchanged for such purposes 
as activating and deactivating explicit and virtual 
routes and sending load modules to adjacent periph- 
eral nodes. See also data flow control layer and 
session control. 

Network Control Program (NCP). An IBM licensed 
program that provides communication controller 
support for single-domain, multiple-domain, and inter- 
connected network capability. Its full name is 
Advanced Communications Function for the Network 
Control Program. 

network control program. A program, generated by 
the user from a library of IBM-supplied modules, that 
controls the operation of a communication controller. 

network log. A file that contains all messages proc- 
essed by the NetView program. 

network management vector transport (NMVT). A 

management services request/response unit (RU) that 
flows over an active session between physical unit 
management services and control point management 
services (SSCP-PU session). 

network name. (1) In SNA, the symbolic identifier by 
which end users refer to a network addressable unit 
(NAU), a link, or a link station. See also network 
address. (2) In a multiple-domain network, the name 
of the APPL statement defining a VTAM application 
program is its network name and it must be unique 
across domains. Contrast with ACB name. See unin- 
terpreted name. 



network operator. (1) A person or program respon- 
sible for controlling the operation of all or part of a 
network. (2) The person or program that controls all 
the domains in a multiple-domain network. Contrast 
with domain operator. 

Network Problem Determination Application (NPOA). 

An IBM licensed program that helps you identify 
network problems, such as hardware, software, and 
microcode, from a central control point using interac- 
tive display techniques. It runs as an NCCF communi- 
cation network management (CNM) application 
program. Its function is included and enhanced in 
NetView's hardware monitor. 

network product support (NPS). The function of the 
NetView program that provides operations control for 
the IBM 3710 Network Controller, 5860 family of 
modems, and the NCP; and configuration of 3710s and 
the 5860 family of modems. NPS provides operator 
commands to run diagnostics for link problem determi- 
nation and to change product operating parameters. 

network services (NS). In SNA, the services within 
network addressable units (NAUs) that control network 
operation through SSCP-SSCP, SSCP-PU, and SSCP-LU 
sessions. See configuration services, maintenance 
services, management services, and session services. 

network services (NS) header. In SNA, a 3-byte field in 
a function management data (FMD) request/response 
unit (RU) flowing in an SSCP-LU, SSCP-PU, or 
SSCP-SSCP session. The network services header is 
used primarily to identify the network services category 
of the request unit (RU) (for example, configuration ser- 
vices, session services) and the particular request 
code within a category. 

NMVT. Network management vector transport. 

NNT. NetView-NetView task. 

node. (1) In SNA, an endpoint of a link or junction 
common to two or more links in a network. Nodes can 
be distributed to host processors, communication con- 
trollers, cluster controllers, or terminals. Nodes can 
vary in routing and other functional capabilities. See 
boundary node, host node, peripheral node, and 
subarea node (including illustration). (2) In VTAM, a 
point in a network defined by a symbolic name. See 
major node and minor node. 

node name. In VTAM, the symbolic name assigned to 
a specific major or minor node during network defi- 
nition. 

node type. In SNA, a designation of a node according 
to the protocols it supports and the network address- 
able units (NAUs) that it can contain. Five types are 
defined: 1, 2.0, 2.1, 4, and 5. Type 1, type 2.0, and type 
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2.1 nodes are peripheral nodes; type 4 and type 5 
nodes are subarea nodes. See also type 2.1 node. 

no response. In SNA, a value in the 
form-of-response-requested field of the request header 
(RH) indicating that no response is to be returned to the 
request, whether or not the request is received and 
processed successfully. Contrast with definite . 
response and exception response. 

NPDA. Network Problem Determination Application. 

NPS. Network product support. 

NS. Network services. 

OCCF. Operator Communication Control Facility. 

online. Stored in a computer and accessible from a 
terminal. 

open. (1) In the IBM Token-Ring Network, to make an 
adapter ready for use. (2) A break in an electrical 
circuit. 

operand. (1) (ISO) An entity on which an operation is 
performed. (2) * That which is operated upon. An 
operand is usually identified by an address part of an 
instruction. (3) Information entered with a command 
name to define the data on which a command 
processor operates and to control the execution of the 
command processor. (4) An expression to whose 
value an operator is applied. See also definition state- 
ment, keyword, keyword parameter, and parameter. 

operator. (1) In a language statement, the lexical 
entity that indicates the action to be performed on oper- 
ands. (2) A person who operates a machine. See 
network operator. See also definition statement. 

Operator Communication Control Facility (OCCF). A 

licensed program that allows communication with and 
the operation of remote MVS or VSE systems. 

operator profile. In the NetView program, the 
resources and activities a network operator has control 
over. The statements defining these resources and 
activities are stored in a file that is activated when the 
operator logs on. 

operator station task (OST). The NetView task that 
establishes and maintains the online session with the 
network operator. There is one operator station task 
for each network operator who logs on to the NetView 
program. See NetView-NetView task. 

OST. Operator station task. 

pacing. In SNA, a technique by which a receiving com- 
ponent controls the rate of transmission of a sending 
component to prevent overrun or congestion. See 



session-level pacing, send pacing, and virtual route 
(VR) pacing. See also flow control. 

pacing group. In SNA, (1) The path information units 
(PIUs) that can be transmitted on a virtual route before 
a virtual-route pacing response is received, indicating 
that the virtual route receiver is ready to receive more 
PIUs on the route. Synonymous with window. (2) The 
requests that can be transmitted on the normal flow in 
one direction on a session before a session-level 
pacing response is received, indicating that the 
receiver is ready to accept the next group of requests. 

pacing group size. In SNA, (1) The number of path 
information units (PIUs) in a virtual route pacing group. 
The pacing group size varies according to traffic con- 
gestion along the virtual route. Synonymous with 
window size. (2) The number of requests in a 
session-level pacing group. 

pacing response. In SNA, an indicator that signifies a 
receiving component's readiness to accept another 
pacing group; the indicator is carried in a response 
header (RH) for session-level pacing, and in a trans- 
mission header (TH) for virtual route pacing. 

page. (1) The portion of a panel that is shown on a 
display surface at one time. (2) To move back and 
forth among the pages of a multiple-page panel. See 
also scroll. (3) (ISO) In a virtual storage system, a 
fixed-length block that has a virtual address and that 
can be transferred between real storage and auxiliary 
storage. (4) To transfer instructions, data, or both 
between real storage and external page or auxiliary 
storage. 

panel. (1) A formatted display of information that 
appears on a terminal screen. See also help panel and 
task panel. Contrast with screen. (2) In computer 
graphics, a display image that defines the locations and 
characteristics of display fields on a display surface. 

parameter. (1) (ISO) A variable that is given a con- 
stant value for a specified application and that may 
denote the application. (2) An item in a menu for 
which the user specifies a value or for which the 
system provides a value when the menu is interpreted. 
(3) Data passed to a program or procedure by a user 
or another program, namely as an operand in a lan- 
guage statement, as an item in a menu, or as a shared 
data structure. See also keyword, keyword parameter, 
and operand. 

partitioned data set (PDS). A data set in direct access 
storage that is divided into partitions, called members, 
each of which can contain a program, part of a 
program, or data. 

path. (1) In SNA, the series of path control network 
components (path control and data link control) that are 
traversed by the information exchanged between two 
network addressable units (NAUs). See also explicit 



Glossary 259 



route (ER), route extension, and virtual route (VR). 
(2) In VTAM when defining a switched major node, a 
potential dial-out port that can be used to reach that 
node. (3) In the NetView/PC program, a complete line 
in a configuration that contains all of the resources in 
the service point command service (SPCS) query link 
configuration request list. 

path control (PC). The function that routes message 
units between network addressable units (NAUs) in the 
network and provides the paths between them. It con- 
verts the BlUs from transmission control (possibly seg- 
menting them) into path information units (PIUs) and 
exchanges basic transmission units (BTUs) and one or 
more PIUs with data link control. Path control differs 
for peripheral nodes, which use local addresses for 
routing, and subarea nodes, which use network 
addresses for routing. See peripheral path control and 
subarea path control. See also link, peripheral node, 
and subarea node. 

path control (PC) layer. In SNA, the layer that 
manages the sharing of link resources of the SNA 
network and routes basic information units (BlUs) 
through it. See also BIU segment, blocking of PIUs, 
data link control layer, and transmission control layer. 



unit (PU) type 1, 2.0, or 2.1 node connected to a 
subarea node with boundary function within a subarea. 
See boundary node, host node, node, peripheral host 
node, subarea host node, and subarea node. See also 
boundary function and node type. 

peripheral path control. The function in a peripheral 
node that routes message units between units with 
local addresses and provides the paths between them. 
See path control and subarea path control. See also 
boundary function, peripheral node, and subarea node. 

peripheral PU. In SNA, a physical unit representing a 
peripheral node. 

permanent error. A resource error that cannot be 
resolved by error recovery programs. Contrast with 
temporary error. 

Personal Computer (PC). The IBM Personal Computer 
line of products including the 5150 and subsequent 
models. 

physical connection. In VTAM, a point-to-point con- 
nection or multipoint connection. Synonymous with 
connection. 



path control (PC) network. In SNA, the part of the SNA 
network that includes the data link control and path 
control layers. See SNA network and user application 
network. See also boundary function. 

path information unit (PIU). In SNA, a message unit 
consisting of a transmission header (TH) alone, or of a 
TH followed by a basic information unit (BIU) or a BIU 
segment. See also transmission header. 



physical unit (PU). In SNA, a type of network address- 
able unit (NAU). A physical unit (PU) manages and 
monitors the resources (such as attached links) of a 
node, as requested by a system services control point 
(SSCP) through an SSCP-PU session. An SSCP acti- 
vates a session with the physical unit in order to indi- 
rectly manage, through the PU, resources of the node 
such as attached links. See also peripheral PU and 
subarea PU. 



PC. (1) Path control. (2) Personal Computer. Its full 
name is the IBM Personal Computer. 

PCID. Procedure-correlation identifier. 



physical unit (PU) services. In SNA, the components 
within a physical unit (PU) that provide configuration 
services and maintenance services for SSCP-PU ses- 
sions. See also logical unit (LU) services. 



performance error. Synonym for temporary error. 



PLU. Primary logical unit. 



peripheral host node. A node that provides an applica- 
tion program interface (API) for running application 
programs but does not provide SSCP functions and is 
not aware of the network configuration. The peripheral 
host node does not provide subarea node services. It 
has boundary function provided by its adjacent 
subarea. See boundary node, host node, node, periph- 
eral node, subarea host node, and subarea node. See 
also boundary function and node type. 



POI. Programmed operator interface. 

positional operand. An operand in a language state- 
ment that has a fixed position. See also definition 
statement. Contrast with keyword operand. 

positive response. A response indicating that a 
request was received and processed. Contrast with 
negative response. 



peripheral LU. In SNA, a logical unit representing a 
peripheral node. 

peripheral node. In SNA, a node that uses local 
addresses for routing and therefore is not affected by 
changes in network addresses. A peripheral node 
requires boundary-function assistance from an adja- 
cent subarea node. A peripheral node is a physical 



POST. Power-on self test. A series of diagnostic tests 
that are run each time the computer's power is turned 
on. 

PPT. Primary POI task. 

presentation services command processor (PSCP). In 

the NetView program, a facility that processes requests 
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from a user terminal and formats displays to be pre- 
sented at the user terminal. 

primary half-session. In SNA, the half-session that 
sends the session activation request. See also primary 
logical unit. Contrast with secondary half-session. 

primary logical unit (PLU). In SNA, the logical unit (LU) 
that contains the primary half-session for a particular 
LU-LU session. Each session must have a PLU and 
secondary logical unit (SLU). The PLU is the unit 
responsible for the bind and is the controlling LU for 
the session. A particular LU may contain both primary 
and secondary half-sessions for different active LU-LU 
sessions. Contrast with secondary logical unit (SLU). 

primary POI task (PPT). The NetView subtask that 
processes all unsolicited messages received from the 
VTAM program operator interface (POI) and delivers 
them to the controlling operator or to the command 
processor. The PPT also processes the initial 
command specified to execute when the NetView 
program is initialized and timer request commands 
scheduled to execute under the PPT. 



communication system that must be followed if commu- 
nication is to be achieved. (3) In SNA, the meanings of, 
and the sequencing rules for, requests and responses 
used for managing the network, transferring data, and 
synchronizing the states of network components. See 
also bracket protocol. Synonymous with line control 
discipline and line discipline. See also link protocol. 

PSCP. Presentation services command processor. 

PU. Physical unit. 

public network. A network established and operated 
by communication common carriers or telecommuni- 
cation Administrations for the specific purpose of pro- 
viding circuit-switched, packet switched, and 
leased-circuit services to the public. Contrast with 
user-application network. 

PU-PU flow. In SNA, the exchange between physical 
units (PUs) of network control requests and responses. 

receive pacing. In SNA, the pacing of message units 
that the component is receiving. See also send pacing. 



problem determination. The process of identifying the 
source of a problem; for example, a program compo- 
nent, a machine failure, telecommunication facilities, 
user or contractor-installed programs or equipment, an 
environment failure such as a power loss, or a user 
error. 

procedure-correlation identifier (PCID). In SNA, a 
value used by a control point to correlate requests and 
replies. 

profile. In the Conversational Monitor System (CMS) 
or the group control system (GCS), the characteristics 
defined by a PROFILE EXEC file that executes automat- 
ically after the system is loaded into a virtual machine. 
See also operator profile. 

programmed operator. A VTAM application program 
that is authorized to issue VTAM operator commands 
and receive VTAM operator awareness messages. See 
also solicited messages and unsolicited messages. 

programmed operator interface (POI). A VTAM func- 
tion that allows programs to perform VTAM operator 
functions. 

protection key. An indicator that appears in the 
current program status word whenever an associated 
task has control of the system. This indicator must 
match the storage keys of all main storage locks that 
the task is to use. 

protocol. (1) (CCITT/ITU) A specification for the 
format and relative timing of information exchanged 
between communicating parties. (2) (TC97) The set of 
rules governing the operation of functional units of a 



RECFMS. Record formatted maintenance statistics. 

RECMS. Record maintenance statistics. 

record. (1) (ISO) In programming languages, an 
aggregate that consists of data objects, possibly with 
different attributes, that usually have identifiers 
attached to them. In some programming languages, 
records are called structures. (2) (TC97) A set of data 
treated as a unit. (3) A set of one or more related data 
items grouped for processing. (4) In VTAM, the unit of 
data transmission for record mode. A record repres- 
ents whatever amount of data the transmitting node 
chooses to send. 

record formatted maintenance statistics (RECFMS). A 

statistical record built by an SNA controller and usually 
solicited by the host. 

record maintenance statistics (RECMS). An SNA error 
event record built from an NCP or line error and sent 
unsolicited to the host. 

reentrant. The attribute of a program or routine that 
allows the same copy of the program or routine to be 
used concurrently by two or more tasks. For example, 
the 3710 Network Controller routines may be reentrant. 

regular command. In the NetView program, any VTAM 
or NetView command that is not an immediate 
command and is processed by a regular command 
processor. Contrast with immediate command. 

release. For VTAM, to relinquish control of resources 
(communication controllers or physical units). See also 
resource takeover. Contrast with acquire (2). 
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remote. Concerning the peripheral parts of a network 
not centrally linked to the host processor and generally 
using telecommunication lines with public right-of-way. 

remove. In the IBM Token-Ring Network, to take an 
attaching device off the ring. 

REQMS. Request for maintenance statistics. 

request for maintenance statistics (REQMS). A host 
solicitation to an SNA controller for a statistical data 
record. 

request header (RH). In SNA, control information pre- 
ceding a request unit (RU). See also request/ response 
header (RH). 

request parameter list (RPL). In VTAM, a control block 
that contains the parameters necessary for processing 
a request for data transfer, for establishing or termi- 
nating a session, or for some other operation. 

request unit (RU). In SNA, a message unit that con- 
tains control information, end-user data, or both. 

request/response header (RH). In SNA, control infor- 
mation, preceding a request/response unit (RU), that 
specifies the type of RU {request unit or response unit) 
and contains control information associated with that 
RU. 

request/response unit (RU). In SNA, a generic term for 
a request unit or a response unit. See also request unit 
(RU) and response unit. 

reset. On a virtual circuit, reinitialization of data flow 
control. At reset, all data in transit are eliminated. 

resource. (1) Any facility of the computing system or 
operating system required by a job or task, and 
including main storage, input/output devices, the proc- 
essing unit, data sets, and control or processing pro- 
grams. (2) In the NetView program, any hardware or 
software that provides function to the network. 



response time. (1) The amount of time it takes after a 
user presses the enter key at the terminal until the 
reply appears at the terminal. (2) For response time 
monitoring, the time from the activation of a transaction 
until a response is received, according to the response 
time definition coded in the performance class. 

response unit (RU). In SNA, a message unit that 
acknowledges a request unit; it may contain prefix 
information received in a request unit, if positive, the 
response unit may contain additional information (such 
as session parameters in response to Bind Session), or 
if negative, contains sense data defining the exception 
condition. 

Restructured Extended Executor (REXX). An interpre- 
tive language used to write command lists. 

return code. * A code [returned from a program] used 
to influence the execution of succeeding instructions. 

REXX. Restructured Extended Executor. 

RH. Request/response header. 

route. See explicit route and virtual route. 

route extension (REX). In SNA, the path control 
network components, including a peripheral link, that 
make up the portion of a path between a subarea node 
and a network addressable unit (NAU) in an adjacent 
peripheral node. See also path, explicit route (ER) and 
virtual route (VR). 

routing. The assignment of the path by which a 
message will reach its destination. 

RPL. Request parameter list. 

RPL exit routine. In VTAM, an application program exit 
routine whose address has been placed in the EXIT 
field of a request parameter list (RPL). VTAM invokes 
the routine to indicate that an asynchronous request 
has been completed. See EXLST exit routine. 



resource takeover. In VTAM, action initiated by a 
network operator to transfer control of resources from 
one domain to another. See also acquire (2) and 
release. See takeover. 

response. A reply represented in the control field of a 
response frame. It advises the primary or combined 
station of the action taken by the secondary or other 
combined station to one or more commands. See also 
command. 

response header (RH). in SNA, a header, optionally 
followed by a response unit (RU), that indicates 
whether the response is positive or negative and that 
may contain a pacing response. See also negative 
response, pacing response, and positive response. 



RU. Request/response unit. 

RU chain. In SNA, a set of related request/response 
units (RUs) that are consecutively transmitted on a par- 
ticular normal or expedited data flow. The request RU 
chain is the unit of recovery: if one of the RUs in the 
chain cannot be processed, the entire chain is dis- 
carded. Each RU belongs to only one chain, which has 
a beginning and an end indicated by means of control 
bits in request/response headers within the RU chain. 
Each RU can be designated as first-in-chain (FIC), 
last-in-chain (LIC), middle-in-chain (MIC), or 
only-in-chain (OIC). Response units and expedited-flow 
request units are always sent as only-in-chain. 
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same-domain. Refers to communication between enti- 
ties in the same SNA domain. Contrast with 
cross-domain. See also single-domain network. 

scope of commands. In the NetView program, the 
facility that provides the ability to assign different 
responsibilities to various operators. 

screen. An illuminated display surface; for example, 
the display surface of a CRT or plasma panel. Contrast 
with panel. 

scroll. To move all or part of the display image verti- 
cally to display data that cannot be observed within a 
single display image. See also page (2). 

SDLC. Synchronous Data Link Control. 

secondary half-session. In SNA, the half-session that 
receives the session-activation request. See also sec- 
ondary logical unit (SLU). Contrast with primary 
half-session. 

secondary logical unit (SLU). In SNA, the logical unit 
(LU) that contains the secondary half-session for a par- 
ticular LU-LU session. An LU may contain secondary 
and primary half-sessions for different active LU-LU 
sessions. Contrast with primary logical unit (PLU). 

secondary logical unit (SLU) key. A key-encrypting key 
used to protect a session cryptography key during its 
transmission to the secondary half-session. 

segment. (1) In the IBM Token-Ring Network, a 
section of cable between components or devices on the 
network. A segment may consist of a single patch 
cable, multiple patch cables connected together, or a 
combination of building cable and patch cables con- 
nected together. (2) See link connection segment. 

send pacing. In SNA, pacing of message units that a 
component is sending. See also receive pacing. 

sequence number. A number assigned to a particular 
frame or packet to control the transmission flow and 
receipt of data. 

Service Level Reporter (SLR). A licensed program that 
generates management reports from data sets such as 
System Management Facility (SMF) files. 

service point (SP). An entry point that supports appli- 
cations that provide network management for 
resources not under the direct control of itself as an 
entry point. Each resource is either under the direct 
control of another entry point or not under the direct 
control of any entry point. A service point accessing 
these resources is not required to use SNA sessions 
(unlike a focal point). A service point is needed when 
entry point support is not yet available for some 
network management function. 



service reminder (SR). In the NetView/PC program, a 
notification set by the operator that is displayed on a 
panel and logs a specified message. 

session. In SNA, a logical connection between two 
network addressable units (NAUs) that can be acti- 
vated, tailored to provide various protocols, and deacti- 
vated, as requested. Each session is uniquely 
identified in a transmission header (TH) by a pair of 
network addresses, identifying the origin and destina- 
tion NAUs of any transmissions exchanged during the 
session. See half-session, LU-LU session, SSCP-LU 
session, SSCP-PU session, and SSCP-SSCP session. 
See also LU-LU session type and PU-PU flow. 

session awareness (SAW) data. Data collected by the 
NetView program about a session that includes the 
session type, the names of session partners, and infor- 
mation about the session activation status. It is col- 
lected for LU-LU, SSCP-LU, SSCP-PU, and SSCP-SSCP 
sessions and for non-SNA terminals not supported by 
NTO. It can be displayed in various forms, such as 
most recent sessions lists. 

session control (SC). In SNA, (1) One of the compo- 
nents of transmission control. Session control is used 
to purge data flowing in a session after an unrecover- 
able error occurs, to resynchronize the data flow after 
such an error, and to perform cryptographic verifica- 
tion. (2) A request unit (RU) category used for requests 
and responses exchanged between the session control 
components of a session and for session activation and 
deactivation requests and responses. 

session-initiation request. In SNA, an Initiate or logon 
request from a logical unit (LU) to a control point (CP) 
that an LU-LU session be activated. 

session-level pacing. In SNA, a flow control technique 
that permits a receiver to control the data transfer rate 
(the rate at which it receives request units) on the 
normal flow. It is used to prevent overloading a 
receiver with unprocessed requests when the sender 
can generate requests faster than the receiver can 
process them. See also pacing and virtual route 
pacing. 

session monitor. The component of the NetView 
program that collects and correlates session-related 
data and provides online access to this information. 

session services, in SNA, one of the types of network 
services in the control point (CP) and in the logical unit 
(LU). These services provide facilities for an LU or a 
network operator to request that the SSCP initiate or 
terminate sessions between logical units. See config- 
uration services, maintenance services, and manage- 
ment services. 

simulated logon. A session-initiation request gener- 
ated when a VTAM application program issues a 
SIMLOGON macroinstruction. The request specifies a 
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logical unit (LU) with which the application program 
wants a session in which the requesting application 
program will act as the primary logical unit (PLU). 

single-domain network. In SNA, a network with one 
system services control point (SSCP). Contrast with 
multiple-domain network. 

SLR. Service Level Reporter. 

SLU. Secondary logical unit. 

SMF. System management facility. 

SNA. Systems Network Architecture. 

SNA network. The part of a user-application network 
that conforms to the formats and protocols of Systems 
Network Architecture. It enables reliable transfer of 
data among end users and provides protocols for con- 
trolling the resources of various network configura- 
tions. The SNA network consists of network 
addressable units (NAUs), boundary function compo- 
nents, and the path control network. 

solicited message. A response from VTAM to a 
command entered by a program operator. Contrast 
with unsolicited message. 

SP. Service point. 

span. In the NetView program, a user-defined group of 
network resources within a single domain. Each major 
or minor node is defined as belonging to one or more 
spans. See also span of control. 

span of control. The total network resources over 
which a particular network operator has control. All 
the network resources listed in spans associated 
through profile definition with a particular network 
operator are within that operator's span of control. 

SR. Service reminder. 

SS. Start-stop. 

SSCP. System services control point. 

SSCP-LU session. In SNA, a session between a 
system services control point (SSCP) and a logical unit 
(LU); the session enables the LU to request the SSCP to 
help initiate LU-LU sessions. 

SSCP-PU session. In SNA, a session between a 
system services control point (SSCP) and a physical 
unit (PU); SSCP-PU sessions allow SSCPs to send 
requests to and receive status information from indi- 
vidual nodes in order to control the network configura- 
tion. 

SSCP-SSCP session. In SNA, a session between the 
system services control point (SSCP) in one domain 



and the SSCP in another domain. An SSCP-SSCP 
session is used to initiate and terminate cross-domain 
LU-LU sessions. 

SSP. System Support Programs (IBM licensed 
program). Its full name is Advanced Communications 
Function for System Support Programs. Synonymous 
with ACF/SSP. 

ST. Session configuration screen abbreviation. 

start option. In VTAM, a user-specified or 
IBM-supplied option that determines certain conditions 
that are to exist during the time a VTAM system is 
operating. Start options can be predefined or specified 
when VTAM is started. 

statement. A language syntactic unit consisting of an 
operator, or other statement identifier, followed by one 
or more operands. See definition statement. 

station. (1) One of the input or output points of a 
network that uses communication facilities; for 
example, the telephone set in the telephone system or 
the point where the business machine interfaces with 
the channel on a leased private line. (2) One or more 
computers, terminals, or devices at a particular 
location. 

status monitor. A component of the NetView program 
that collects and summarizes information on the status 
of resources defined in a VTAM domain. 

subarea. A portion of the SNA network consisting of a 
subarea node, any attached peripheral nodes, and their 
associated resources. Within a subarea node, all 
network addressable units, links, and adjacent link 
stations (in attached peripheral or subarea nodes) that 
are addressable within the subarea share a common 
subarea address and have distinct element addresses. 

subarea host node. A host node that provides both 
subarea function and an application program interface 
(API) for running application programs. It provides 
system services control point (SSCP) functions, 
subarea node services, and is aware of the network 
configuration. See boundary node, communication 
management configuration host node, data host node, 
host node, node, peripheral node, and subarea node. 
See also boundary function and node type. 

subarea node. In SNA, a node that uses network 
addresses for routing and whose routing tables are 
therefore affected by changes in the configuration of 
the network. Subarea nodes can provide gateway func- 
tion, and boundary function support for peripheral 
nodes. Type 4 and type 5 nodes are subarea nodes. 
See boundary node, host node, node, peripheral node, 
and subarea host node. See also boundary function 
and node type. 
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subarea path control. The function in a subarea node 
that routes message units between network address- 
able units (NAUs) and provides the paths between 
them. See path control and peripheral path control. 
See also boundary function, peripheral node, and 
subarea node. 



through and controlling the configuration and operation 
of networks. 

System Support Programs (SSP). An IBM licensed 
program, made up of a collection of utilities and small 
programs, that supports the operation of the NCP. 



subarea PU. 

node. 



In SNA, a physical unit (PU) in a subarea 



subsystem. A secondary or subordinate system, 
usually capable of operating independent of, or asyn- 
chronously with, a controlling system. 

supervisor. The part of a control program that coordi- 
nates the use of resources and maintains the flow of 
processing unit operations. 

suppression character. In the NetView program, a 
user-defined character that is coded at the beginning of 
a command list statement or a command to prevent the 
statement or command from appearing on the opera- 
tor's terminal screen or in the network log. 

Synchronous Data Link Control (SDLC). A discipline 
for managing synchronous, code-transparent, 
serial-by-bit information transfer over a link con- 
nection. Transmission exchanges may be duplex or 
half-duplex over switched or nonswitched links. The 
configuration of the link connection may be 
point-to-point, multipoint, or loop. SDLC conforms to 
subsets of the Advanced Data Communication Control 
Procedures (ADCCP) of the American National Stand- 
ards Institute and High-Level Data Link Control (HDLC) 
of the International Standards Organization. 

system management facility (SMF). A standard feature 
of MVS that collects and records a variety of system 
and job-related information. 

system services control point (SSCP). In SNA, a 
central location point within an SNA network for man- 
aging the configuration, coordinating network operator 
and problem determination requests, and providing 
directory support and other session services for end 
users of the network. Multiple SSCPs, cooperating as 
peers, can divide the network into domains of control, 
with each SSCP having a hierarchical control relation- 
ship to the physical units and logical units within its 
domain. 

system services control point (SSCP) domain. The 

system services control point and the physical units 
(PUs), logical units (LUs), links, link stations and all the 
resources that the SSCP has the ability to control by 
means of activation requests and deactivation 
requests. 

Systems Network Architecture (SNA). The description 
of the logical structure, formats, protocols, and opera- 
tional sequences for transmitting information units 



TAF. Terminal access facility. 

takeover. The process by which the failing active sub- 
system is released from its extended recovery facility 
(XRF) sessions with terminal users and replaced by an 
alternate subsystem. See resource takeover. 

task. A basic unit of work to be accomplished by a 
computer. The task is usually specified to a control 
program in a multiprogramming or multiprocessing 
environment. 

task panel. Online display from which you communi- 
cate with the program in order to accomplish the pro- 
gram's function, either by selecting an option provided 
on the panel or by entering an explicit command. See 
help panel. 

telecommunication line. Any physical medium such as 
a wire or microwave beam, that is used to transmit 
data. Synonymous with transmission line. 

temporary error. A resource failure that can be 
resolved by error recovery programs. Synonymous 
with performance error. Contrast with permanent 
error. 

terminal. A device that is capable of sending and 
receiving information over a link; it is usually equipped 
with a keyboard and some kind of display, such as a 
screen or a printer. 

terminal access facility (TAF). In the NetView 
program, a facility that allows a network operator to 
control a number of subsystems. In a full-screen or 
operator control session, operators can control any 
combination of such subsystems simultaneously. 

TERMINATE. In SNA, a request unit that is sent by a 
logical unit (LU) to its system services control point 
(SSCP) to cause the SSCP to start a procedure to end 
one or more designated LU-LU sessions. 

TH. Transmission header. 

threshold. In the NetView program, refers to a per- 
centage value set for a resource and compared to a 
calculated error-to-traffic ratio. 

threshold analysis and remote access. (1) A compo- 
nent of the NetView program that can notify a central 
operator about network problems and errors. It pro- 
vides remote control of IBM 3600 and 4700 controllers 
and can record, analyze, and display performance and 
status data on IBM 3600 and 4700 Finance Communi- 
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cations Systems. (2) The feature of the back-level 
NPDA licensed program that performs some of these 
functions. 

time sharing option (TSO). An optional configuration of 
the operating system that provides conversational time 
sharing from remote stations. 

token. A sequence of bits passed from one device to 
another along the token ring. When the token has data 
appended to it, it becomes a frame. 

transmission control (TC) layer. In SNA, the layer 
within a half-session that synchronizes and paces 
session-level data traffic, checks session sequence 
numbers of requests, and enciphers and deciphers 
end-user data. Transmission control has two compo- 
nents: the connection point manager and session 
control. See also half-session. 

transmission header (TH). In SNA, control information, 
optionally followed by a basic information unit (BIU) or 
a BIU segment, that is created and used by path control 
to route message units and to control their flow within 
the network. See also path information unit. 



transmission line. 

line. 



Synonym for telecommunication 



TSO. Time sharing option. 

tutorial. Online information presented in a teaching 
format. 

type 2.1 node (T2.1 node). A node that can attach to an 
SNA network as a peripheral node using the same pro- 
tocols as type 2.0 nodes. Type 2.1 nodes can be 
directly attached to one another using peer-to-peer pro- 
tocols. See end node, node, and subarea node. See 
also node type. 

type 2.1 node (T2.1 node) control point domain. The 

CP, its logical units (LUs), links, link stations, and all 
resources that it activates and deactivates. 

unformatted. In VTAM, pertaining to commands (such 
as LOGON or LOGOFF) entered by an end user and 
sent by a logical unit in character form. The 
character-coded command must be in the syntax 
defined in the user's unformatted system services defi- 
nition table. Synonymous with character-coded. Con- 
trast with field-formatted. 

unformatted system services (USS). In SNA products, 
a system services control point (SSCP) facility that 
translates a character-coded request, such as a logon 
or logoff request into a field-formatted request for proc- 
essing by formatted system services and translates 
field-formatted replies and responses into 
character-coded requests for processing by a logical 
unit. Contrast with formatted system services. See 
also converted command. 



uninterpreted name. In SNA, a character string that a 
system services control point (SSCP) is able to convert 
into the network name of a logical unit (LU). Typically, 
an uninterpreted name is used in a logon or Initiate 
request from a secondary logical unit (SLU) to identify 
the primary logical unit (PLU) with which the session is 
requested. 

unsolicited message. A message, from VTAM to a 
program operator, that is unrelated to any command 
entered by the program operator. Contrast with solic- 
ited message. 

upstream. In the direction of data flow from the end 
user to the host. Contrast with downstream. 

user. Anyone who requires the services of a com- 
puting system. 

user-application network. A configuration of data proc- 
essing products, such as processors, controllers, and 
terminals, established and operated by users for the 
purpose of data processing or information exchange, 
which may use services offered by communication 
common carriers or telecommunication Adminis- 
trations. Contrast with public network. 

user exit. A point in an IBM-supplied program at which 
a user routine may be given control. 

user exit routine. A user-written routine that receives 
control at predefined user exit points. User exit rou- 
tines can be written in assembler or a high-level lan- 
guage (HLL). 

USS. Unformatted system services. 

value. (1) (TC97) A specific occurrence of an attri- 
bute, for example, "blue" for the attribute "color." (2) A 
quantity assigned to a constant, a variable, a param- 
eter, or a symbol. 

variable. In the NetView program, a character string 
beginning with & that is coded in a command list and is 
assigned a value during execution of the command list. 

vector. The MAC frame information field. 

verb. (1) In SNA, the general name for a transaction 
program's request for communication services. (2) In 
VTAM, a programming language element in the logical 
unit (LU) 6.2 application program interface (API) that 
causes an LU 6.2 function to be performed. 

Virtual Machine (VM). A licensed program whose full 
name is the Virtual Machine/System Product (VM/SP). 
It is a software operating system that manages the 
resources of a real processor to provide virtual 
machines to end users. As a time-sharing system 
control program, it consists of the virtual machine 
control program (CP), the conversational monitor 



266 NetView Customization: Assembler 



system (CMS), the group control system (GCS), and the 
interactive problem control system (IPCS). 

virtual route (VR). In SNA, a logical connection (1) 
between two subarea nodes that is physically realized 
as a particular explicit route, or (2) that is contained 
wholly within a subarea node for intranode sessions. A 
virtual route between distinct subarea nodes imposes a 
transmission priority on the underlying explicit route, 
provides flow control through virtual-route pacing, and 
provides data integrity through sequence numbering of 
path information units (PIUs). See also explicit route 
(ER), path, and route extension. 

virtual route (VR) pacing. In SNA, a flow control tech- 
nique used by the virtual route control component of 
path control at each end of a virtual route to control the 
rate at which path information units (PIUs) flow over the 
virtual route. VR pacing can be adjusted according to 
traffic congestion in any of the nodes along the route. 
See also pacing and session-level pacing. 

virtual route selection exit routine. In VTAM, an 
optional installation exit routine that modifies the list of 
virtual routes associated with a particular class of 
service before a route is selected for a requested 
LU-LU session. 

virtual storage. (ISO) The notion of storage space that 
may be regarded as addressable main storage by the 
user of a computer system in which virtual addresses 
are mapped into real addresses. The size of virtual 
storage is limited by the addressing scheme of the 
computer system and by the amount of auxiliary 
storage available, not by the actual number of main 
storage locations. 

Virtual Storage Access Method (VSAM). An access 
method for direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key field (key sequence), in the 
physical sequence in which they are written on the data 
set or file (entry-sequence), or by relative-record 
number. 

Virtual Storage Extended (VSE). An IBM licensed 
program whose full name is the Virtual Storage 
Extended/Advanced Function. It is a software oper- 
ating system controlling the execution of programs. 

Virtual Telecommunications Access Method (VTAM). 

An IBM licensed program that controls communication 
and the flow of data in an SNA network. It provides 
single-domain, multiple-domain, and interconnected 
network capability. 



VM. Virtual Machine operating system. Its full name is 
Virtual Machine/System Product. Synonymous with 
VM/SP. 

VM SNA console support (VSCS). A VTAM component 
for the VM environment that provides Systems Network 
Architecture (SNA) support. It allows SNA terminals to 
be virtual machine consoles. 

VM/SP. Virtual Machine/System Product operating 
system. Synonym for VM. 

VR. Virtual route. 

VSAM. Virtual Storage Access Method. 

VSCS. VM SNA console support. 

VSE. Virtual Storage Extended operating system. Syn- 
onymous with VSE/AF. 

VSE/AF. Virtual Storage Extended/Advanced Function 
operating system. Synonym for VSE. 

VSE/OCCF. Virtual Storage Extended/Operator Com- 
munication Control Facility. 

VTAM. Virtual Telecommunications Access Method 
(IBM licensed program). Its full name is Advanced 
Communications Function for the Virtual Telecommuni- 
cations Access Method. Synonymous with ACF/VTAM. 

VTAM application program. A program that has 
opened an ACB to identify itself to VTAM and can now 
issue VTAM macroinstructions. 

VTAM operator command. A command used to 
monitor or control a VTAM domain. See also definition 
statement. 

window. (1) In SNA, synonym for pacing group. 
(2) On a visual display terminal, a small amount of 
information in a framed-in area on a panel that over- 
lays part of the panel. (3) In data communication, the 
number of data packets a data terminal equipment 
(DTE) or data circuit-terminating equipment (DCE) can 
send across a logical channel before waiting for 
authorization to send another data packet. The window 
is the main mechanism of pacing, or flow control, of 
packets. 

window size. (1) The specified number of frames of 
information that can be sent before receiving an 
acknowledgment response. (2) In SNA, synonym for 
pacing group size. 
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Learning About NetView: Operator Training 
(SK2T-0292) is an interactive PC-based operator 
training package that teaches SNA and basic network 
management concepts to new and inexperienced 
NetView operators. This training package uses 
graphics, animation and interactive NetView product 
simulations in a series of lessons to teach the basics of 
NetView operation. 

NetView Installation and Administration Guide 
(SC31-6018) helps system programmers install and 
prepare the NetView program for operation. It is 
arranged in a simplified, step-by-step style and is 
meant to be used in conjunction with the sample 
network documented in Network Program Products 
Samples. 

NetView Administration Reference (SC31-6014) is for 
system programmers and network operators who need 
a complete understanding of the NetView resource defi- 
nition statements. This book lists each statement in 
alphabetical order giving its purpose and location. 

NetView Tuning Guide (SC31-6079)e describes methods 
for controlling and improving the performance of the 
NetView Release 3 program. It is designed for system 
programmers who need to understand how NetView 
tuning values are determined and optimized. 

NetView Customization Guide (SC31-6016) is designed 
for system programmers and others who want to cus- 
tomize the NetView program to reflect their network's 
needs or operating procedures. This book focuses on 
the different application programming interfaces that 
can be customized and explains how to modify NetView 
help panels and problem determination displays. 

NetView Customization: Using PUI and C (SC31-6037) 
describes the ways system programmers can tailor the 
NetView program to satisfy unique requirements or 
operating procedures. It discusses the uses and 
advantages of user-written programs (exit routines, 
command processors, and subtasks). It also provides 
instructions in designing, writing, and installing user- 
written programs in PL/I and C. 

NetView Customization: Using Assembler (SC31-6078) 
describes the ways system programmers can tailor the 
NetView program to satisfy unique requirements or 
operating procedures. It discusses the uses and 



advantages of user-written programs (exit routines, 
command processors, and subtasks). It also provides 
instructions in designing, writing, and installing user- 
written programs in Assembler. 

NetView Customization: Writing Command Lists 
(SC31-6015) explains how to simplify network operator 
tasks by using command lists. It provides step-by-step 
instructions for writing simple and advanced command 
lists and for migrating from nccf message automation 
to NetView message automation. 

NetView Operation Primer (SC31-6020) provides a 
basic description of the network management task for 
new network operators. Topics include starting and 
stopping a network, controlling resources, monitoring a 
network, and gathering the necessary data to report a 
problem. 

NetView Operation (SC31-6019) provides system pro- 
grammers and experienced network operators a com- 
prehensive explanation of network management using 
the NetView program. Topics include detailed 
command explanation and panel flows, as well as infor- 
mation on how the various components interact with 
each other. 

NetView Command Summary (SX75-0026) is a refer- 
ence card that provides network operators with the 
format of all the commands and the commonly used 
NetView command lists. The commands are listed in 
alphabetical order by component. 

NetView Problem Determination and Diagnosis 
(LY43-0001) aids system programmers in identifying a 
NetView problem, classifying it, and describing it to an 
ibm Support Center. 

NetView Problem Determination Supplement for Man- 
agement Services Major Vectors 0001 and 0025 
(LD21 -0023) describes major vectors 0001 and 0025 for 
system programmers and network operators involved 
in problem determination or diagnosis. The supple- 
ment may be used for the generic alert option and 
other problem determination tasks. 

NetView Resource Alerts Reference (SC31-6024) lists 
the messages sent by NetView-supported hardware 
and software resources. It helps system programmers 
analyze the messages into their component parts: 
action codes, event types, message text, and qualifiers. 
The book is a reference for those who need more infor- 
mation than online help provides. 
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NetView Storage Estimates (SK2T-1988) is an interac- 
tive PC-based tool that helps the user estimate storage 
requirements for NetView. This tool can be used for 
planning, installation, and tuning purposes. It is 
intended for network planners, system programmers, 
and IBM service personnel. 

Console Automation Using NetView: Planning 
(SC31-6058) describes an approach to automate the 
way a system handles messages and responses to 
alerts. It includes information you should know before 
beginning such automation, as well as sample plans 
and proposals you might find useful in promoting your 
automation concept. This book includes planning infor- 
mation for MVS, VM, and VSE users of the NetView 
program. 

NetView/PC Publications 

NetViewlPC Planning, Installation, and Customization 
(SC31-6002) provides planning, installation, and 
customization information on NetView/PC and explains 
the communication requirements upstream to the host 
and downstream to supported devices. Information 
relating to the required pc environment and host pro- 
ducts that support NetView/PC is also provided. It also 
discusses topics that are of general interest when you 
are ordering your equipment. 

NetView/PC Application Program 
Interface/Communications Services Reference 
(SC31-6004) is a reference for os/2 programmers who 
use the api/cs and for system programmers who write 
command processors to run under NetView. The api/cs 
provides a means for vendor and other external appli- 
cations to use the communication services of 
NetView/PC. 

NetView/ PC Operation (SC31-6003) describes how to 
operate the program and diagnose problems in 
NetView/PC. 

NetViewlPC Quick Reference (SX75-0016) describes all 
of the functions of the F-keys throughout the 
NetView/PC program. 



Other Network Program 
Products Publications 



For more information about the books listed in this 
section, see Bibliography and Master Index for 
NetView, NCP, and VTAM. 

Network Program Products General Information 
(GC30-3350) 



Network Program Products Planning (SC30-3351) 

Network Program Products Samples (SC30-3352) 

Bibliography and Master Index for NetView, NCP, and 
VTAM (GC31-6081)7 

VTAM Publications 

The following list shows the books for vtam V3FI2. For 
information about the books for vtam V3R1, V3R1.1, or 
V3R1.2, see any vtam V3R2 book or the Network Program 
Products Bibliography and Master Index. 

VTAM Installation and Resource Definition (SC23-0111) 

VTAM Customization (LY30-5614) 

VTAM Directory of Programming Interfaces for Cus- 
tomers (GC31-6403) 

VTAM Operation (SC23-01 13) 

VTAM Messages and Codes (SC23-0114) 

VTAM Programming (SC23-0115) 

VTAM Programming for LU 6.2 (SC30-3400) 

VTAM Diagnosis Guide (LY30-5601) 

VTAM Data Areas for MVS (LY30-5592) 

VTAM Data Areas for VM (LY30-5593) 

VTAM Data Areas for VSE (LY30-5594) 

VTAM Reference Summary (LY30-5600) 

NCP, SSP, and EP Publications 

The following list shows the related books for ncpv4 
and ncp vs. 

NCP, SSP, and EP Generation and Loading Guide 
(SC30-3348) 

NCP, SSP, and Related Products Directory of Program- 
ming Interfaces for Customers (GC31-6202) 

NCP Migration Guide (SC30-3252 for NCP V4 and 
SC30-3440 for NCP V5) 

NCP, SSP, and EP Resource Definition Guide 
(SC30-3349 for NCP V4 and SC30-3447 for NCP V5) 



7 This book will be available by December 1989. 
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NCP, SSP, and EP Resource Definition Reference 
(SC30-3254 for NCP V4 and SC30-3448 for NCP V5) 

NCP and EP Reference Summary and Data Areas 
(LY30-5570 for NCP V4 and LY30-5603 for NCP V5) 

NCP Customization Guide (LY30-5571 for NCP V4 
LY30-5606 for NCP V5) 

NCP Customization Reference (LY30-5612 for NCP V4 
and LY30-5607 for NCP V5) 

SSP Customization (LY43-0021) 

NCP, SSP, and EP Messages and Codes (SC30-3169) 

NCP, SSP, and EP Diagnosis Guide (LY30-5591) 



NCP and EP Reference (LY30-5569 for NCP V4 and 
LY30-5605 for NCP V5) 



Related Publications 

VM/SP System Product Interpreter Reference or TSO/E 
RE XX Reference (SC28-1883) (referred to in this book 
as REXX Reference.) 

IBM 3600/4700 Threshold Analysis and Remote Access 
Feature: General Information (GC34-2055) 

IBM 3600/4700 Threshold Analysis and Remote Access 
Feature: User's Guide (SC34-2056) 

IBM 3600/4700 Threshold Analysis and Remote Access 
Feature: Installation and Customization (SC34-2041) 
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